@codefast/cli 0.3.15 → 0.3.16-canary.0

package/dist/{domains/arrange/domain/constants.domain.mjs → arrange/domain/constants.mjs}

@@ -1,51 +1,87 @@
-//#region src/domains/arrange/domain/constants.domain.ts
+//#region src/arrange/domain/constants.ts
 /**
 * Analyze report: long literal threshold (token count).
-*/ const LONG_STRING_TOKEN_THRESHOLD = 18;
+*
+* @since 0.3.16-canary.0
+*/
+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).
-*/ const APPLY_MIN_TOKENS = 2;
+*
+* @since 0.3.16-canary.0
+*/
+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.
-*/ const MIN_GROUP_TOKENS = 2;
+*
+* @since 0.3.16-canary.0
+*/
+const MIN_GROUP_TOKENS = 2;
 /**
 * Dynamic max groups clamp: base bound.
-*/ const MAX_GROUPS_BASE = 4;
+*
+* @since 0.3.16-canary.0
+*/
+const MAX_GROUPS_BASE = 4;
 /**
 * Dynamic max groups clamp: upper cap.
-*/ const MAX_GROUPS_CAP = 24;
+*
+* @since 0.3.16-canary.0
+*/
+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`).
-*/ const MAX_GROUPS_HEADROOM = 2;
+*
+* @since 0.3.16-canary.0
+*/
+const MAX_GROUPS_HEADROOM = 2;
 /**
 * Maximum findings printed per category in the analyze report.
-*/ const MAX_REPORT_LINES = 40;
+*
+* @since 0.3.16-canary.0
+*/
+const MAX_REPORT_LINES = 40;
 /**
 * Maximum recursion depth when traversing `tv()` object literals.
-*/ const MAX_OBJECT_DEPTH = 12;
+*
+* @since 0.3.16-canary.0
+*/
+const MAX_OBJECT_DEPTH = 12;
 /**
 * Maximum depth when peeling conditional / parens / arrays inside `cn(...)` args.
-*/ const MAX_CLASS_EXPR_DEPTH = 12;
+*
+* @since 0.3.16-canary.0
+*/
+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.
-*/ const MAX_STRIP_VARIANT_PASSES = 12;
+*
+* @since 0.3.16-canary.0
+*/
+const MAX_STRIP_VARIANT_PASSES = 12;
 /**
 * Passed when optional `knownBindings` is missing — size 0 disables matching
 * for `cn` / `tv` identifier resolution.
-*/ const EMPTY_CN_TV_BINDINGS = /* @__PURE__ */ new Set();
+*
+* @since 0.3.16-canary.0
+*/
+const EMPTY_CN_TV_BINDINGS = /* @__PURE__ */ new Set();
 /**
 * Bucket sort order — **render pipeline** (lower → earlier in `cn()` output).
-*
+* 
 * Matches README: Existence → Position → Layout → Sizing → Spacing → Shape → Background
 * → Shadow → Typography → Composite → Motion → Starting → Behavior → State → Selector,
 * then `other` and `arbitrary` as sort tails for unknown utilities and arbitrary properties.
-*/ const BUCKET_ORDER = {
+*
+* @since 0.3.16-canary.0
+*/
+const BUCKET_ORDER = {
 	existence: 0,
 	position: 1,
 	layout: 2,
@@ -72,7 +108,10 @@
 * `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.
-*/ const COMPATIBLE_BUCKET_SETS = [
+*
+* @since 0.3.16-canary.0
+*/
+const COMPATIBLE_BUCKET_SETS = [
 	new Set(["existence", "position"]),
 	new Set(["existence", "layout"]),
 	new Set(["position", "layout"]),
@@ -90,13 +129,19 @@
 ];
 /**
 * Responsive / variant prefix — Tailwind v4 aware.
-*
+* 
 * v3: sm: md: … — v4: @sm:, @min-[600px]:, @[480px]:, named @md/sidebar:,
 * viewport md/sidebar:, min-[100px]: / max-[100px]:, …
-*/ 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-)\[[^\]]+\]:)/;
+*
+* @since 0.3.16-canary.0
+*/
+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).
-*/ const STATE_PREFIXES = new Set([
+*
+* @since 0.3.16-canary.0
+*/
+const STATE_PREFIXES = new Set([
 	"hover",
 	"focus",
 	"focus-within",

package/dist/{domains/arrange/domain/arrange-grouping.domain-service.mjs → arrange/domain/grouping-service.mjs}

@@ -1,12 +1,9 @@
-import { applyEditsDescending } from "../../../shell/domain/source-text-edit.support.mjs";
-import { buildKnownCnTvBindings, unwrapCnInsideTvCallReplacement } from "./ast/ast-helpers.helper.mjs";
-import { listAllCnCallsInsideTvInSourceFile } from "./ast/collectors-tv.collector.mjs";
-import { collectGroupTargets, planGroupEditForTarget, targetReplaceStart } from "./ast/targets.model.mjs";
-//#region src/domains/arrange/domain/arrange-grouping.domain-service.ts
-/**
-* Rich domain: plan Tailwind class grouping / cn-in-tv unwrap for a single file.
-* Pure: only DomainSourceFile, source strings, and options — no I/O.
-*/ function toUnwrapPlans(cnInTvCalls, sourceText) {
+import { applyEditsDescending } from "../../core/source-text-edit.mjs";
+import { buildKnownCnTvBindings, unwrapCnInsideTvCallReplacement } from "./ast/helpers.mjs";
+import { listAllCnCallsInsideTvInSourceFile } from "./ast/collectors-tv.mjs";
+import { collectGroupTargets, planGroupEditForTarget, targetReplaceStart } from "./ast/targets.mjs";
+//#region src/arrange/domain/grouping-service.ts
+function toUnwrapPlans(cnInTvCalls, sourceText) {
 	return cnInTvCalls.map((call) => {
 		const replacement = unwrapCnInsideTvCallReplacement(call, sourceText);
 		if (replacement === void 0) return;
@@ -18,6 +15,9 @@ import { collectGroupTargets, planGroupEditForTarget, targetReplaceStart } from
 		};
 	}).filter((plan) => plan !== void 0);
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function buildGroupFileUnwrapState(domainSfInitial, sourceText) {
 	const cnInTvCalls = listAllCnCallsInsideTvInSourceFile(domainSfInitial, buildKnownCnTvBindings(domainSfInitial));
 	const unwrapPlans = toUnwrapPlans(cnInTvCalls, sourceText);
@@ -34,7 +34,10 @@ function buildGroupFileUnwrapState(domainSfInitial, sourceText) {
 /**
 * `domainSfGrouped` must be a parse of `unwrap.textAfterUnwrap` (same `text` as source).
 * Returns `null` when there is no cn-in-tv and no grouping targets.
-*/ function tryBuildGroupFileWorkPlan(input) {
+*
+* @since 0.3.16-canary.0
+*/
+function tryBuildGroupFileWorkPlan(input) {
 	const { filePath, sourceText, domainSfInitial, domainSfGrouped, withClassName, unwrap } = input;
 	if (domainSfGrouped.text !== unwrap.textAfterUnwrap) throw new Error("Domain invariant: domainSfGrouped.text must match unwrap phase textAfterUnwrap");
 	const groupTargets = collectGroupTargets(domainSfGrouped, filePath);
@@ -64,6 +67,9 @@ function buildGroupFileUnwrapState(domainSfInitial, sourceText) {
 		editSitesCount
 	};
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function groupFileDryRunNoEdits(filePath) {
 	return {
 		filePath,
@@ -71,6 +77,9 @@ function groupFileDryRunNoEdits(filePath) {
 		changed: 0
 	};
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function groupFilePreviewTotals(work) {
 	return {
 		filePath: work.filePath,
@@ -78,6 +87,9 @@ function groupFilePreviewTotals(work) {
 		changed: 0
 	};
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function mergeGroupFileBodyText(work) {
 	const groupEdits = work.plannedGroupEdits.map((plannedEdit) => ({
 		start: plannedEdit.start,
@@ -87,12 +99,21 @@ function mergeGroupFileBodyText(work) {
 	}));
 	return groupEdits.length > 0 ? applyEditsDescending(work.textAfterUnwrap, groupEdits) : work.textAfterUnwrap;
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function groupFileEditsTouchJsxCn(work) {
 	return work.plannedGroupEdits.some((plannedEdit) => plannedEdit.jsxCn);
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function countPersistedGroupFileEdits(work) {
 	return work.unwrapEdits.length + work.plannedGroupEdits.length;
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function groupFileWorkHasNothingToReport(work) {
 	return work.editSitesCount === 0 && work.cnInTvNoReplacement === 0;
 }

package/dist/{domains/arrange/domain/grouping.domain.mjs → arrange/domain/grouping.mjs}

@@ -1,14 +1,16 @@
-import { BUCKET_ORDER } from "./constants.domain.mjs";
-import { stripVariants, tokenizeClassString } from "./tailwind-token.value-object.mjs";
-import { bucketsCompatible, bucketsMergeCompatible, classifyToken, compositeSecondaryOrder, selectorKey, stateKey } from "./tailwind-token-classifier.domain-service.mjs";
-//#region src/domains/arrange/domain/grouping.domain.ts
+import { BUCKET_ORDER } from "./constants.mjs";
+import { stripVariants, tokenizeClassString } from "./tailwind-token.mjs";
+import { bucketsCompatible, bucketsMergeCompatible, classifyToken, compositeSecondaryOrder, selectorKey, stateKey } from "./token-classifier.mjs";
+//#region src/arrange/domain/grouping.ts
 /**
 * `cn()` grouping: bucket sequence is {@link BUCKET_ORDER} only; tokens are classified with
 * {@link classifyToken}. Comparators here (`compareClassifiedTailwindTokensForCnGrouping`, …)
 * are the single place for variant-aware sort — do not reintroduce parallel bucket ordering.
-*/ /**
+*/
+/**
 * Separates bucket id from variant key in {@link buildFirstVariantKeySourceIndex} map keys.
-*/ const VARIANT_BUCKET_KEY_SEP = "\0";
+*/
+const VARIANT_BUCKET_KEY_SEP = "\0";
 function isVariantKeyedBucket(bucket) {
 	return bucket === "selector" || bucket === "state" || bucket === "starting";
 }
@@ -21,13 +23,15 @@ function variantKeyedBlockMapKey(bucket, classToken) {
 /**
 * Deterministic lexicographic order for Tailwind class tokens (and token-space signatures).
 * Used wherever we need stable, locale-agnostic ASCII ordering of utility strings.
-*/ function compareClassTokensCanonically(left, right) {
+*/
+function compareClassTokensCanonically(left, right) {
 	return left.localeCompare(right);
 }
 /**
 * First source index where each `(bucket, variantGroupKey)` appears — drives stable clustering
 * in {@link suggestCnGroups} without reordering unrelated variant blocks by alphabet alone.
-*/ function buildFirstVariantKeySourceIndex(classified) {
+*/
+function buildFirstVariantKeySourceIndex(classified) {
 	const firstVariantKeySourceIndex = /* @__PURE__ */ new Map();
 	for (const item of classified) {
 		if (!isVariantKeyedBucket(item.bucket)) continue;
@@ -62,7 +66,10 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 * 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.
-*/ function areCnTailwindPartitionsEquivalent(staticLiteralTexts, suggestedGroups) {
+*
+* @since 0.3.16-canary.0
+*/
+function areCnTailwindPartitionsEquivalent(staticLiteralTexts, suggestedGroups) {
 	const partitionSignatures = (chunks) => chunks.map((chunk) => {
 		const classTokens = tokenizeClassString(chunk);
 		return classTokens.length === 0 ? "" : [...classTokens].sort(compareClassTokensCanonically).join(" ");
@@ -75,7 +82,8 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 }
 /**
 * Dominant bucket of a whitespace-delimited class group (for merge heuristics).
-*/ function dominantBucketOfGroup(groupStr) {
+*/
+function dominantBucketOfGroup(groupStr) {
 	const counts = /* @__PURE__ */ new Map();
 	for (const classToken of tokenizeClassString(groupStr)) {
 		const tokenBucket = classifyToken(classToken);
@@ -95,7 +103,8 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 }
 /**
 * Dynamic cap: more tokens → allow more groups, within [BASE, CAP].
-*/ function dynamicMaxGroups(tokenCount) {
+*/
+function dynamicMaxGroups(tokenCount) {
 	const byTokens = Math.ceil(tokenCount / 2) + 2;
 	return Math.max(4, Math.min(24, byTokens));
 }
@@ -107,7 +116,8 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 * 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.
-*/ function mergeSingletons(groups) {
+*/
+function mergeSingletons(groups) {
 	if (groups.length <= 1) return groups;
 	const result = [...groups];
 	let changed = true;
@@ -145,7 +155,8 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 }
 /**
 * Tie-break when two merge candidates are both {@link bucketsMergeCompatible} (same bucket or COMPATIBLE_BUCKET_SETS).
-*/ function capMergePenalty(leftBucket, rightBucket) {
+*/
+function capMergePenalty(leftBucket, rightBucket) {
 	if (leftBucket === rightBucket) return 0;
 	if (bucketsCompatible(leftBucket, rightBucket)) return 0;
 	return 500;
@@ -159,7 +170,8 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 * 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.
-*/ function capGroups(groups, maxGroups) {
+*/
+function capGroups(groups, maxGroups) {
 	const result = [...groups];
 	const lengths = result.map((groupStr) => tokenizeClassString(groupStr).length);
 	while (result.length > maxGroups) {
@@ -202,7 +214,8 @@ function compareClassifiedTailwindTokensForCnGrouping(left, right, firstVariantK
 * **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.
-*/ function mergeEaseTimingIntoFollowingAnimatedState(groups) {
+*/
+function mergeEaseTimingIntoFollowingAnimatedState(groups) {
 	const result = [...groups];
 	let changed = true;
 	while (changed) {
@@ -237,6 +250,9 @@ function chunkIsOnlyEaseTimingMotion(groupStr) {
 	if (classTokens.length === 0) return false;
 	return classTokens.every((classToken) => classifyToken(classToken) === "motion" && /^ease-/.test(stripVariants(classToken)));
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function suggestCnGroups(classString) {
 	const tokens = tokenizeClassString(classString);
 	if (tokens.length === 0) return [];
@@ -247,7 +263,8 @@ function suggestCnGroups(classString) {
 	* variants. Block order follows the **first source index** of each key so unrelated
 	* states keep document order; within a key, `classToken` order is lexicographic for
 	* idempotency.
-	*/ const classified = tokens.map((classToken, index) => ({
+	*/
+	const classified = tokens.map((classToken, index) => ({
 		classToken,
 		bucket: classifyToken(classToken),
 		index
@@ -257,7 +274,8 @@ function suggestCnGroups(classString) {
 	const rawGroups = [];
 	/**
 	* Bucket of the last token already placed in the current run (pairwise compat with `COMPATIBLE_BUCKET_SETS`).
-	*/ let lastBucketInRun = null;
+	*/
+	let lastBucketInRun = null;
 	let currentStateKey = null;
 	let currentTokens = [];
 	const flush = () => {
@@ -304,7 +322,10 @@ function suggestCnGroups(classString) {
 /**
 * 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).
-*/ function summarizeGroupBucketLabels(groups) {
+*
+* @since 0.3.16-canary.0
+*/
+function summarizeGroupBucketLabels(groups) {
 	return groups.map((g) => {
 		const uniq = new Set(tokenizeClassString(g).map(classifyToken));
 		if (uniq.size !== 1) return `mixed:${[...uniq].sort(compareClassTokensCanonically).join("+")}`;

package/dist/{domains/arrange/domain/imports.domain.mjs → arrange/domain/imports.mjs}

@@ -1,5 +1,5 @@
-import { isDomainImportDeclaration, isDomainNamedImports, isDomainStringLiteral } from "./ast/ast-node.model.mjs";
-//#region src/domains/arrange/domain/imports.domain.ts
+import { isDomainImportDeclaration, isDomainNamedImports, isDomainStringLiteral } from "./ast/ast-node.mjs";
+//#region src/arrange/domain/imports.ts
 function sourceFileImportsCn(sourceFile) {
 	for (const statement of sourceFile.statements) {
 		if (!isDomainImportDeclaration(statement) || !statement.importClause) continue;
@@ -13,7 +13,8 @@ function sourceFileImportsCn(sourceFile) {
 }
 /**
 * Resolve the module specifier used when injecting a `cn` import into a file.
-*/ function cnModuleSpecifierForFile(filePath, override) {
+*/
+function cnModuleSpecifierForFile(filePath, override) {
 	if (override) return override;
 	return "@codefast/tailwind-variants";
 }
@@ -24,6 +25,9 @@ function findImportDeclarationFromModule(sourceFile, moduleSpecifier) {
 		if (isDomainStringLiteral(spec) && spec.text === moduleSpecifier) return statement;
 	}
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function ensureCnImport(sourceFile, cnImportOverride) {
 	const sourceText = sourceFile.text;
 	if (sourceFileImportsCn(sourceFile)) return sourceText;

package/dist/{domains/arrange/domain/source-text-formatters.formatter.mjs → arrange/domain/source-text-formatters.mjs}

@@ -1,15 +1,20 @@
-import { indentOfLineContaining } from "../../../shell/domain/source-text-edit.support.mjs";
-//#region src/domains/arrange/domain/source-text-formatters.formatter.ts
+import { indentOfLineContaining } from "../../core/source-text-edit.mjs";
+//#region src/arrange/domain/source-text-formatters.ts
+/**
+* @since 0.3.16-canary.0
+*/
 function escapeTsStringLiteralContent(group) {
 	return group.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
 }
-/** Trailing comma on multiline Tailwind group lists (matches prior `cn` / `tv` array style). */ function commaAfterTailwindGroupLine(groupIndex, groupCount) {
+/** Trailing comma on multiline Tailwind group lists (matches prior `cn` / `tv` array style). */
+function commaAfterTailwindGroupLine(groupIndex, groupCount) {
 	return groupIndex < groupCount - 1 || groupCount > 1 ? "," : "";
 }
 /**
 * Multiline fragment for use *inside* an existing `cn(...)` — replaces one
 * string argument with several, without producing `cn(cn(...))`.
-*/ function formatCnArguments(groups, options) {
+*/
+function formatCnArguments(groups, options) {
 	const indent = options?.indent ?? "  ";
 	const commaAfterLast = options?.commaAfterLastGroup ?? options?.trailingClassName ?? false;
 	const lines = [];
@@ -22,6 +27,9 @@ function escapeTsStringLiteralContent(group) {
 	if (options?.trailingClassName) lines.push(`${indent}className,`);
 	return lines.join("\n");
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function formatCnCall(groups, options) {
 	const lines = ["cn("];
 	const commaOnEachStringLine = groups.length > 1 || Boolean(options?.trailingClassName);
@@ -35,6 +43,9 @@ function formatCnCall(groups, options) {
 	lines.push(")");
 	return lines.join("\n");
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function formatArray(groups) {
 	const lines = ["["];
 	for (let i = 0; i < groups.length; i++) {
@@ -49,7 +60,10 @@ function formatArray(groups) {
 /**
 * Multiple string literals as sequential lines for insertion **inside** an existing array
 * (e.g. `tv({ base: [ … ] })` — avoids `[[ "a", "b" ]]` when replacing one long string).
-*/ function formatArrayElementsAsSiblingLines(groups, continuationPrefix) {
+*
+* @since 0.3.16-canary.0
+*/
+function formatArrayElementsAsSiblingLines(groups, continuationPrefix) {
 	const segments = [];
 	for (let i = 0; i < groups.length; i++) {
 		const group = groups[i];
@@ -60,6 +74,9 @@ function formatArray(groups) {
 	}
 	return segments.join("");
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function formatJsxCnAttributeValue(groups, source, valueNodeStart) {
 	const baseIndent = indentOfLineContaining(source, valueNodeStart);
 	return `{cn(\n${formatCnArguments(groups, {

package/dist/{domains/arrange/domain/tailwind-token.value-object.mjs → arrange/domain/tailwind-token.mjs}

@@ -1,5 +1,8 @@
-import "./constants.domain.mjs";
-//#region src/domains/arrange/domain/tailwind-token.value-object.ts
+import "./constants.mjs";
+//#region src/arrange/domain/tailwind-token.ts
+/**
+* @since 0.3.16-canary.0
+*/
 function tokenizeClassString(classString) {
 	return classString.trim().split(/\s+/).filter(Boolean);
 }
@@ -7,7 +10,10 @@ function tokenizeClassString(classString) {
 * Index of the first `:` that separates a Tailwind variant segment from the rest.
 * Colons inside `[...]` (at positive bracket depth) are ignored so selectors like
 * `[&_a:hover]:text-red-500` split as `[&_a:hover]:` + `text-red-500`.
-*/ function indexOfFirstVariantColon(text) {
+*
+* @since 0.3.16-canary.0
+*/
+function indexOfFirstVariantColon(text) {
 	let depth = 0;
 	for (let i = 0; i < text.length; i++) {
 		const ch = text[i];
@@ -17,6 +23,9 @@ function tokenizeClassString(classString) {
 	}
 	return -1;
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function stripVariants(token) {
 	let withoutVariants = token;
 	const maxStripVariantPasses = 12;

package/dist/{domains/arrange/domain/tailwind-token-classifier.domain-service.mjs → arrange/domain/token-classifier.mjs}

@@ -1,6 +1,6 @@
-import { COMPATIBLE_BUCKET_SETS, RESPONSIVE_PREFIX, STATE_PREFIXES } from "./constants.domain.mjs";
-import { indexOfFirstVariantColon, stripVariants } from "./tailwind-token.value-object.mjs";
-//#region src/domains/arrange/domain/tailwind-token-classifier.domain-service.ts
+import { COMPATIBLE_BUCKET_SETS, RESPONSIVE_PREFIX, STATE_PREFIXES } from "./constants.mjs";
+import { indexOfFirstVariantColon, stripVariants } from "./tailwind-token.mjs";
+//#region src/arrange/domain/token-classifier.ts
 /**
 * Bare-token classification is **total** (always returns a {@link Bucket}). The `Result` pattern
 * (`isOk` / `isErr`) belongs at arrange use-case / I/O boundaries, not on this hot path.
@@ -9,7 +9,8 @@ import { indexOfFirstVariantColon, stripVariants } from "./tailwind-token.value-
 * numbered `nth-*`, media features, v4 `in-[…]`, child selectors `*` / `**`, …).
 * When these are missed, `isStateToken` is false and the variant is stripped — the
 * utility is then bucketed as if it were unconditional, which breaks preview grouping.
-*/ function isCompoundOrMediaVariantPrefix(prefix) {
+*/
+function isCompoundOrMediaVariantPrefix(prefix) {
 	if (prefix === "*" || prefix === "**") return true;
 	if (prefix === "inert") return true;
 	if (prefix.startsWith("has-")) return true;
@@ -22,7 +23,8 @@ import { indexOfFirstVariantColon, stripVariants } from "./tailwind-token.value-
 }
 /**
 * Outermost variant segment: first `:` at bracket depth 0 → text before it.
-*/ function firstLeadingVariantPrefix(token) {
+*/
+function firstLeadingVariantPrefix(token) {
 	const colonIdx = indexOfFirstVariantColon(token);
 	if (colonIdx === -1) return;
 	return token.slice(0, colonIdx);
@@ -58,7 +60,10 @@ function isStateToken(token) {
 /**
 * Secondary sort inside the **composite** bucket: opacity / blend / isolation →
 * 3D context → 3D transforms → 2D transforms → filters → will-change.
-*/ function compositeSecondaryOrder(bareUtility) {
+*
+* @since 0.3.16-canary.0
+*/
+function compositeSecondaryOrder(bareUtility) {
 	const b = bareUtility;
 	if (/^opacity(?:-|$)/.test(b) || /^mix-blend-/.test(b) || /^isolation(?:-|$)/.test(b) || b === "isolate") return 0;
 	if (b === "transform-3d" || /^perspective(?:-|$)/.test(b)) return 10;
@@ -71,7 +76,8 @@ function isStateToken(token) {
 }
 /**
 * Classify a **bare** utility (no `hover:` / `md:` / … prefixes).
-*/ function classifyBareUtility(bareUtility) {
+*/
+function classifyBareUtility(bareUtility) {
 	const b = bareUtility;
 	if (/^@container(?:\/[a-z][a-z0-9-]*)?$/i.test(b)) return "existence";
 	if (/^(?:hidden|contents|sr-only|not-sr-only|list-item|flow-root)$/.test(b) || /^(?:block|inline-block|inline)$/.test(b)) return "existence";
@@ -98,13 +104,17 @@ function isStateToken(token) {
 * scope utilities to descendants — bucket as `selector` so they chunk apart from base layout/typography
 * and are labeled distinctly from interactive `state` variants (`hover:`, `data-[…]:`, …).
 * Pure arbitrary **properties** (`[--x]:`, `[color:red]`) have no `&` in the leading `[…]` segment.
-*/ function isArbitraryParentSelectorStateToken(token) {
+*/
+function isArbitraryParentSelectorStateToken(token) {
 	if (/^\[&/.test(token)) return true;
 	if (!token.startsWith("[")) return false;
 	const colonIdx = indexOfFirstVariantColon(token);
 	if (colonIdx === -1 || colonIdx === 0 || token[colonIdx - 1] !== "]") return false;
 	return token.slice(0, colonIdx).includes("&");
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function classifyToken(token) {
 	if (isArbitraryParentSelectorStateToken(token)) return "selector";
 	if (isSelectorVariantToken(token)) return "selector";
@@ -122,19 +132,22 @@ function classifyToken(token) {
 * Stable key for `data-[…]` variants so unrelated selectors stay split, while
 * **branching on the full bracket** (e.g. `data-[vaul-drawer-direction=bottom]`
 * vs `=left`) keeps direction-specific utilities in separate state groups.
-*/ function dataAttributeStem(token) {
+*/
+function dataAttributeStem(token) {
 	const match = token.match(/^data-\[([^\]]*)\]/);
 	return match ? `data-[${match[1]}]` : "data";
 }
 /**
 * Same idea as {@link dataAttributeStem} for `aria-[…]:` variants.
-*/ function ariaAttributeStem(token) {
+*/
+function ariaAttributeStem(token) {
 	const match = token.match(/^aria-\[([^\]]*)\]/);
 	return match ? `aria-[${match[1]}]` : "aria";
 }
 /**
 * `in-data-[…]:` — normalize on the full bracket expression like {@link dataAttributeStem}.
-*/ function inDataAttributeStem(token) {
+*/
+function inDataAttributeStem(token) {
 	const match = token.match(/^in-data-\[([^\]]*)\]/);
 	return match ? `in-data-[${match[1]}]` : "in-data";
 }
@@ -144,10 +157,13 @@ function classifyToken(token) {
 * Uses the **full variant stack** (every `:` segment outside `[…]`), not only the
 * outermost prefix, so `@md/foo:[&>*]:w-auto` and `@md/foo:has-[…]:mt-px` stay in
 * separate groups while `hover:opacity` still keys as `hover` + `opacity`…
-*
+* 
 * `data-[…]` / `aria-[…]` normalize the first segment via {@link dataAttributeStem} /
 * {@link ariaAttributeStem} (full token required for bracket capture).
-*/ function stateKey(token) {
+*
+* @since 0.3.16-canary.0
+*/
+function stateKey(token) {
 	const layers = [];
 	let rest = token;
 	while (rest.length > 0) {
@@ -169,20 +185,29 @@ const SELECTOR_KEY_SEP = "";
 * Variant key for {@link Bucket} `"selector"` tokens in {@link suggestCnGroups}.
 * Reuses {@link stateKey} layer splitting, then normalizes common shadcn/Radix SVG patterns so
 * `[&_svg]:…` and `[&_svg:not([class*='size-'])]:…` stay in one chunk.
-*/ function selectorKey(token) {
+*
+* @since 0.3.16-canary.0
+*/
+function selectorKey(token) {
 	return stateKey(token).split(SELECTOR_KEY_SEP).map(normalizeSelectorVariantLayer).join(SELECTOR_KEY_SEP);
 }
 function normalizeSelectorVariantLayer(layer) {
 	if (layer === "[&_svg:not([class*='size-'])]") return "[&_svg]";
 	return layer;
 }
+/**
+* @since 0.3.16-canary.0
+*/
 function bucketsCompatible(a, b) {
 	if (a === b) return true;
 	return COMPATIBLE_BUCKET_SETS.some((bucketSet) => bucketSet.has(a) && bucketSet.has(b));
 }
 /**
 * Like {@link bucketsCompatible}, but never merge two distinct state / starting / selector variant blobs.
-*/ function bucketsMergeCompatible(a, b) {
+*
+* @since 0.3.16-canary.0
+*/
+function bucketsMergeCompatible(a, b) {
 	if (a === "state" && b === "state") return false;
 	if (a === "starting" && b === "starting") return false;
 	if (a === "selector" && b === "selector") return false;