@omnimod/plugin-utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 salnika
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @omnimod/plugin-utils
+
+[![npm](https://img.shields.io/npm/v/%40omnimod%2Fplugin-utils?label=npm)](https://www.npmjs.com/package/@omnimod/plugin-utils)
+[![CI](https://img.shields.io/github/actions/workflow/status/Salnika/omnimod/ci.yml?branch=master&label=ci)](https://github.com/Salnika/omnimod/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/Salnika/omnimod)](../../LICENSE)
+
+Helpers for authoring omnimod plugins.
+
+This package contains shared AST types, CSS-in-JS parsing helpers,
+vanilla-extract serialization helpers, and import editing utilities used by the
+official plugins.
+
+## Install
+
+```bash
+pnpm add @omnimod/plugin-utils
+```
+
+## API
+
+```ts
+import { ImportManager, cast, parseScss, serializeVe } from "@omnimod/plugin-utils";
+```
+
+Main exports:
+
+- `cast`: typed AST node casting helper.
+- `parseScss`, `cssToVeStyle`, `globalRules`, `keyframesToVe`: CSS and SCSS helpers.
+- `ImportManager`: utility for editing import declarations.
+- `serializeVe` and `ve*` helpers: build and print vanilla-extract object values.

package/dist/index.d.mts

@@ -0,0 +1,316 @@
+import { Node } from "@omnimod/core";
+import { Root } from "postcss";
+
+//#region src/ast.d.ts
+/** Reinterpret a generic `Node` as one of the narrowed views below. */
+declare function cast<T extends Node>(node: Node): T;
+interface Identifier extends Node {
+  name: string;
+}
+interface JSXIdentifier extends Node {
+  name: string;
+}
+interface Literal extends Node {
+  value: string | number | boolean | null;
+  raw?: string;
+}
+/** A `Literal` already known to carry a string value. */
+interface StringLiteral extends Node {
+  value: string;
+}
+interface ThisExpression extends Node {
+  type: "ThisExpression";
+}
+interface MemberExpression extends Node {
+  object: Node;
+  property: Node;
+  computed: boolean;
+}
+interface CallExpression extends Node {
+  callee: Node;
+  arguments: Node[];
+}
+interface NewExpression extends Node {
+  callee: Node;
+  arguments: Node[];
+}
+interface ConditionalExpression extends Node {
+  test: Node;
+  consequent: Node;
+  alternate: Node;
+}
+interface BinaryExpression extends Node {
+  operator: string;
+  left: Node;
+  right: Node;
+}
+interface LogicalExpression extends Node {
+  operator: string;
+  left: Node;
+  right: Node;
+}
+interface UnaryExpression extends Node {
+  operator: string;
+  argument: Node;
+}
+interface AssignmentExpression extends Node {
+  operator: string;
+  left: Node;
+  right: Node;
+}
+interface ArrowFunctionExpression extends Node {
+  params: Node[];
+  body: Node;
+  expression: boolean;
+  async?: boolean;
+}
+interface FunctionExpression extends Node {
+  params: Node[];
+  body: Node;
+  async?: boolean;
+}
+interface FunctionDeclaration extends Node {
+  id: Node | null;
+  params: Node[];
+  body: Node;
+}
+interface ObjectExpression extends Node {
+  properties: Node[];
+}
+interface ObjectPattern extends Node {
+  properties: Node[];
+}
+interface ArrayExpression extends Node {
+  elements: (Node | null)[];
+}
+interface Property extends Node {
+  key: Node;
+  value: Node;
+  computed: boolean;
+  shorthand: boolean;
+  kind: string;
+}
+interface AssignmentPattern extends Node {
+  left: Node;
+  right: Node;
+}
+interface BlockStatement extends Node {
+  body: Node[];
+}
+interface ReturnStatement extends Node {
+  argument: Node | null;
+}
+interface ExpressionStatement extends Node {
+  expression: Node;
+}
+interface SwitchStatement extends Node {
+  discriminant: Node;
+  cases: Node[];
+}
+interface VariableDeclarator extends Node {
+  id: Node;
+  init: Node | null;
+}
+interface VariableDeclaration extends Node {
+  declarations: VariableDeclarator[];
+  kind: string;
+}
+interface ImportSpecifier extends Node {
+  imported: Node;
+  local: Identifier;
+  /** "type" for `import type { X }` / `import { type X }`, else "value". */
+  importKind?: string;
+}
+interface ImportDefaultSpecifier extends Node {
+  local: Identifier;
+}
+interface ImportNamespaceSpecifier extends Node {
+  local: Identifier;
+}
+interface ImportDeclaration extends Node {
+  source: StringLiteral;
+  specifiers: Node[];
+}
+interface ExportNamedDeclaration extends Node {
+  declaration: Node | null;
+}
+interface ExportDefaultDeclaration extends Node {
+  declaration: Node;
+}
+interface ClassBody extends Node {
+  body: Node[];
+}
+interface MethodDefinition extends Node {
+  key: Node;
+  value: FunctionExpression;
+  kind: string;
+  static: boolean;
+  computed: boolean;
+}
+interface PropertyDefinition extends Node {
+  key: Node;
+  value: Node | null;
+  static: boolean;
+  computed: boolean;
+}
+interface ClassDeclaration extends Node {
+  id: Identifier | null;
+  superClass: Node | null;
+  body: ClassBody;
+}
+interface ClassExpression extends Node {
+  id: Identifier | null;
+  superClass: Node | null;
+  body: ClassBody;
+}
+interface TemplateElementValue {
+  raw: string;
+  cooked: string | null;
+}
+interface TemplateElement extends Node {
+  value: TemplateElementValue;
+}
+interface TemplateLiteral extends Node {
+  quasis: TemplateElement[];
+  expressions: Node[];
+}
+interface TaggedTemplateExpression extends Node {
+  tag: Node;
+  quasi: TemplateLiteral;
+}
+interface JSXExpressionContainer extends Node {
+  expression: Node;
+}
+interface JSXAttribute extends Node {
+  name: Node;
+  value: Node | null;
+}
+interface JSXSpreadAttribute extends Node {
+  argument: Node;
+}
+interface JSXOpeningElement extends Node {
+  name: Node;
+  attributes: Node[];
+  selfClosing: boolean;
+}
+interface JSXClosingElement extends Node {
+  name: Node;
+}
+interface JSXElement extends Node {
+  openingElement: JSXOpeningElement;
+}
+//#endregion
+//#region src/casing.d.ts
+/**
+ * Convert a CSS property name to the camelCase key vanilla-extract expects.
+ *
+ * - `background-color` → `backgroundColor`
+ * - `-webkit-transition` → `WebkitTransition` (vendor prefixes → PascalCase)
+ * - `-ms-flex` → `msFlex` (the `-ms-` prefix is lowercased, per csstype/React)
+ * - `--my-var` → `--my-var` (custom properties are kept verbatim)
+ */
+declare function cssPropToCamel(prop: string): string;
+//#endregion
+//#region src/ve.d.ts
+/**
+ * A small value model for the object literals vanilla-extract consumes
+ * (`style({...})`, recipe variants, theme contracts). Kept as data so callers
+ * can build/merge objects programmatically, then serialize to source once.
+ *
+ * The `raw` kind escapes serialization: it emits unquoted JS (e.g. a `vars.x.y`
+ * token reference or a `createVar()` handle).
+ */
+type VeValue = {
+  readonly kind: "string";
+  readonly value: string;
+} | {
+  readonly kind: "number";
+  readonly value: number;
+} | {
+  readonly kind: "boolean";
+  readonly value: boolean;
+} | {
+  readonly kind: "raw";
+  readonly code: string;
+} | {
+  readonly kind: "object";
+  readonly entries: readonly VeEntry[];
+} | {
+  readonly kind: "array";
+  readonly items: readonly VeValue[];
+};
+interface VeEntry {
+  readonly key: string;
+  readonly value: VeValue;
+}
+declare const veString: (value: string) => VeValue;
+declare const veNumber: (value: number) => VeValue;
+declare const veBoolean: (value: boolean) => VeValue;
+declare const veRaw: (code: string) => VeValue;
+declare const veObject: (entries: VeEntry[]) => VeValue;
+declare const veArray: (items: VeValue[]) => VeValue;
+/** Serialize a VeValue to formatted TypeScript source (2-space indentation). */
+declare function serializeVe(value: VeValue, indent?: number): string;
+/** True when the value is an object with no entries. */
+declare function isEmptyObject(value: VeValue): boolean;
+//#endregion
+//#region src/css.d.ts
+/** The token inserted where interpolation `index` sat in a styled template. */
+declare function placeholderToken(index: number): string;
+/**
+ * Reconstruct a parseable CSS string from a styled template's static chunks,
+ * inserting an identifier-like placeholder token between each pair (one per
+ * interpolation). `quasis` has length N+1 for N interpolations.
+ */
+declare function buildPlaceholderCss(quasis: string[]): string;
+declare function parseScss(css: string): Root;
+/**
+ * Resolve an interpolation placeholder to a vanilla-extract value. `context`
+ * tells the resolver where the placeholder appeared. Returning `null` means the
+ * interpolation could not be converted (the caller records a warning).
+ */
+type PlaceholderResolver = (token: string, context: "value" | "property" | "selector") => VeValue | null;
+/** A selector that must become `globalStyle(...)`; `selector` keeps `&` as the component placeholder. */
+interface DescendantRule {
+  selector: string;
+  style: VeValue;
+}
+interface VeStyleResult {
+  /** The object for `style({...})` (declarations, pseudos via `selectors`, `@media`). */
+  base: VeValue;
+  /** Selectors that can't live inside `style()` and need `globalStyle()`. */
+  descendants: DescendantRule[];
+  /** Human-readable notes about anything that couldn't be fully converted. */
+  warnings: string[];
+}
+/** Convert a parsed styled-components CSS block into a vanilla-extract style model. */
+declare function cssToVeStyle(root: Root, resolve?: PlaceholderResolver): VeStyleResult;
+/**
+ * Convert a `keyframes` CSS block into the object vanilla-extract's `keyframes()`
+ * expects, keyed by step (`from`, `to`, `0%`, `50%`, …).
+ */
+declare function keyframesToVe(root: Root): VeValue;
+/**
+ * Convert a `createGlobalStyle`/global CSS block into a flat list of
+ * `globalStyle(selector, style)` rules (one per top-level selector).
+ */
+declare function globalRules(root: Root): DescendantRule[];
+//#endregion
+//#region src/imports.d.ts
+/**
+ * Collects import specifiers needed by generated code and renders them as
+ * `import` statements. Deduplicates and sorts for deterministic output.
+ */
+declare class ImportManager {
+  private readonly named;
+  private readonly defaults;
+  /** Require `import { <imported> as <local> } from "<module>"`. */
+  addNamed(module: string, imported: string, local?: string): void;
+  /** Require `import <local> from "<module>"`. */
+  addDefault(module: string, local: string): void;
+  isEmpty(): boolean;
+  /** Render one import statement per module, sorted by module specifier. */
+  render(): string;
+}
+//#endregion
+export { type ArrayExpression, type ArrowFunctionExpression, type AssignmentExpression, type AssignmentPattern, type BinaryExpression, type BlockStatement, type CallExpression, type ClassBody, type ClassDeclaration, type ClassExpression, type ConditionalExpression, type DescendantRule, type ExportDefaultDeclaration, type ExportNamedDeclaration, type ExpressionStatement, type FunctionDeclaration, type FunctionExpression, type Identifier, type ImportDeclaration, type ImportDefaultSpecifier, ImportManager, type ImportNamespaceSpecifier, type ImportSpecifier, type JSXAttribute, type JSXClosingElement, type JSXElement, type JSXExpressionContainer, type JSXIdentifier, type JSXOpeningElement, type JSXSpreadAttribute, type Literal, type LogicalExpression, type MemberExpression, type MethodDefinition, type NewExpression, type ObjectExpression, type ObjectPattern, type PlaceholderResolver, type Property, type PropertyDefinition, type ReturnStatement, type StringLiteral, type SwitchStatement, type TaggedTemplateExpression, type TemplateElement, type TemplateElementValue, type TemplateLiteral, type ThisExpression, type UnaryExpression, type VariableDeclaration, type VariableDeclarator, type VeEntry, type VeStyleResult, type VeValue, buildPlaceholderCss, cast, cssPropToCamel, cssToVeStyle, globalRules, isEmptyObject, keyframesToVe, parseScss, placeholderToken, serializeVe, veArray, veBoolean, veNumber, veObject, veRaw, veString };

package/dist/index.mjs

@@ -0,0 +1,326 @@
+import scss from "postcss-scss";
+//#region src/ast.ts
+/** Reinterpret a generic `Node` as one of the narrowed views below. */
+function cast(node) {
+	return node;
+}
+//#endregion
+//#region src/casing.ts
+/**
+* Convert a CSS property name to the camelCase key vanilla-extract expects.
+*
+* - `background-color` → `backgroundColor`
+* - `-webkit-transition` → `WebkitTransition` (vendor prefixes → PascalCase)
+* - `-ms-flex` → `msFlex` (the `-ms-` prefix is lowercased, per csstype/React)
+* - `--my-var` → `--my-var` (custom properties are kept verbatim)
+*/
+function cssPropToCamel(prop) {
+	const trimmed = prop.trim();
+	if (trimmed.startsWith("--")) return trimmed;
+	return trimmed.replace(/^-ms-/, "ms-").replace(/-([a-z])/g, (_match, char) => char.toUpperCase());
+}
+//#endregion
+//#region src/ve.ts
+const veString = (value) => ({
+	kind: "string",
+	value
+});
+const veNumber = (value) => ({
+	kind: "number",
+	value
+});
+const veBoolean = (value) => ({
+	kind: "boolean",
+	value
+});
+const veRaw = (code) => ({
+	kind: "raw",
+	code
+});
+const veObject = (entries) => ({
+	kind: "object",
+	entries
+});
+const veArray = (items) => ({
+	kind: "array",
+	items
+});
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+function serializeKey(key) {
+	return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+/** Serialize a VeValue to formatted TypeScript source (2-space indentation). */
+function serializeVe(value, indent = 0) {
+	const pad = "  ".repeat(indent);
+	const padInner = "  ".repeat(indent + 1);
+	switch (value.kind) {
+		case "string": return JSON.stringify(value.value);
+		case "number": return String(value.value);
+		case "boolean": return String(value.value);
+		case "raw": return value.code;
+		case "array":
+			if (value.items.length === 0) return "[]";
+			return `[${value.items.map((item) => serializeVe(item, indent)).join(", ")}]`;
+		case "object":
+			if (value.entries.length === 0) return "{}";
+			return `{\n${value.entries.map((entry) => `${padInner}${serializeKey(entry.key)}: ${serializeVe(entry.value, indent + 1)},`).join("\n")}\n${pad}}`;
+	}
+}
+/** True when the value is an object with no entries. */
+function isEmptyObject(value) {
+	return value.kind === "object" && value.entries.length === 0;
+}
+//#endregion
+//#region src/css.ts
+const PLACEHOLDER_PREFIX = "__OMNIMOD_EXPR_";
+const SINGLE_PLACEHOLDER = /^__OMNIMOD_EXPR_(\d+)__$/;
+const PLACEHOLDER_GLOBAL = /__OMNIMOD_EXPR_\d+__/g;
+const NUMERIC = /^-?\d+(?:\.\d+)?$/;
+const DESCENDANT_COMBINATORS = [
+	" ",
+	"	",
+	"\n",
+	">",
+	"+",
+	"~"
+];
+/** The token inserted where interpolation `index` sat in a styled template. */
+function placeholderToken(index) {
+	return `${PLACEHOLDER_PREFIX}${index}__`;
+}
+/**
+* Reconstruct a parseable CSS string from a styled template's static chunks,
+* inserting an identifier-like placeholder token between each pair (one per
+* interpolation). `quasis` has length N+1 for N interpolations.
+*/
+function buildPlaceholderCss(quasis) {
+	let css = "";
+	for (let i = 0; i < quasis.length; i++) {
+		css += quasis[i];
+		if (i < quasis.length - 1) css += placeholderToken(i);
+	}
+	return css;
+}
+function parseScss(css) {
+	return scss.parse(css);
+}
+/** Convert a parsed styled-components CSS block into a vanilla-extract style model. */
+function cssToVeStyle(root, resolve) {
+	const descendants = [];
+	const warnings = [];
+	return {
+		base: convertContainer(root, resolve, descendants, warnings),
+		descendants,
+		warnings
+	};
+}
+/**
+* Convert a `keyframes` CSS block into the object vanilla-extract's `keyframes()`
+* expects, keyed by step (`from`, `to`, `0%`, `50%`, …).
+*/
+function keyframesToVe(root) {
+	const steps = [];
+	const scratchDescendants = [];
+	const scratchWarnings = [];
+	root.each((node) => {
+		if (node.type !== "rule") return;
+		const inner = convertContainer(node, void 0, scratchDescendants, scratchWarnings);
+		for (const rawStep of splitTopLevel(node.selector, [","])) {
+			const step = normalizeSelector(rawStep);
+			if (step.length > 0) steps.push({
+				key: step,
+				value: inner
+			});
+		}
+	});
+	return veObject(steps);
+}
+/**
+* Convert a `createGlobalStyle`/global CSS block into a flat list of
+* `globalStyle(selector, style)` rules (one per top-level selector).
+*/
+function globalRules(root) {
+	const rules = [];
+	const scratchDescendants = [];
+	const scratchWarnings = [];
+	root.each((node) => {
+		if (node.type !== "rule") return;
+		const inner = convertContainer(node, void 0, scratchDescendants, scratchWarnings);
+		for (const rawSelector of splitTopLevel(node.selector, [","])) {
+			const selector = normalizeSelector(rawSelector);
+			if (selector.length > 0) rules.push({
+				selector,
+				style: inner
+			});
+		}
+	});
+	return rules;
+}
+function convertContainer(container, resolve, descendants, warnings) {
+	const entries = [];
+	const selectorEntries = [];
+	const mediaEntries = [];
+	container.each((node) => {
+		if (node.type === "decl") entries.push(declToEntry(node, resolve, warnings));
+		else if (node.type === "rule") classifyRule(node, resolve, descendants, warnings, selectorEntries);
+		else if (node.type === "atrule") handleAtRule(node, resolve, descendants, warnings, mediaEntries);
+	});
+	if (selectorEntries.length > 0) entries.push({
+		key: "selectors",
+		value: veObject(selectorEntries)
+	});
+	if (mediaEntries.length > 0) entries.push({
+		key: "@media",
+		value: veObject(mediaEntries)
+	});
+	return veObject(entries);
+}
+function handleAtRule(atrule, resolve, descendants, warnings, mediaEntries) {
+	if (atrule.name === "media") {
+		const inner = convertContainer(atrule, resolve, descendants, warnings);
+		mediaEntries.push({
+			key: atrule.params,
+			value: inner
+		});
+	} else warnings.push(`Unsupported at-rule @${atrule.name} was left unconverted`);
+}
+function classifyRule(rule, resolve, descendants, warnings, selectorEntries) {
+	const inner = convertContainer(rule, resolve, descendants, warnings);
+	for (const rawSelector of splitTopLevel(rule.selector, [","])) {
+		const selector = normalizeSelector(rawSelector);
+		if (selector.length === 0) continue;
+		if (lastCompound(selector).includes("&")) selectorEntries.push({
+			key: selector,
+			value: inner
+		});
+		else {
+			const withAmp = selector.includes("&") ? selector : `& ${selector}`;
+			descendants.push({
+				selector: withAmp,
+				style: inner
+			});
+		}
+	}
+}
+function declToEntry(decl, resolve, warnings) {
+	return {
+		key: decl.prop.includes(PLACEHOLDER_PREFIX) ? resolvePropName(decl.prop, resolve, warnings) : cssPropToCamel(decl.prop),
+		value: valueToVe(decl.important ? `${decl.value} !important` : decl.value, resolve, warnings)
+	};
+}
+function resolvePropName(prop, resolve, warnings) {
+	if (SINGLE_PLACEHOLDER.exec(prop.trim()) && resolve) {
+		const resolved = resolve(prop.trim(), "property");
+		if (resolved && resolved.kind === "string") return resolved.value;
+	}
+	warnings.push(`Could not statically convert dynamic property name: ${prop}`);
+	return cssPropToCamel(prop);
+}
+function valueToVe(raw, resolve, warnings) {
+	const value = raw.trim();
+	if (!value.includes(PLACEHOLDER_PREFIX)) return NUMERIC.test(value) ? veNumber(Number(value)) : veString(value);
+	if (resolve) if (SINGLE_PLACEHOLDER.test(value)) {
+		const resolved = resolve(value, "value");
+		if (resolved) return resolved;
+	} else {
+		const template = mixedValueToTemplate(value, resolve);
+		if (template !== null) return veRaw(template);
+	}
+	warnings.push(`Could not statically convert dynamic value: ${value}`);
+	return veString(value);
+}
+/** Build a JS template-literal source for a value mixing static text and interpolations. */
+function mixedValueToTemplate(value, resolve) {
+	const parts = [];
+	let lastIndex = 0;
+	for (const match of value.matchAll(PLACEHOLDER_GLOBAL)) {
+		parts.push(escapeTemplate(value.slice(lastIndex, match.index)));
+		const resolved = resolve(match[0], "value");
+		if (!resolved) return null;
+		parts.push(embedInTemplate(resolved));
+		lastIndex = match.index + match[0].length;
+	}
+	parts.push(escapeTemplate(value.slice(lastIndex)));
+	return `\`${parts.join("")}\``;
+}
+function embedInTemplate(value) {
+	switch (value.kind) {
+		case "raw": return `\${${value.code}}`;
+		case "string": return escapeTemplate(value.value);
+		case "number":
+		case "boolean": return String(value.value);
+		default: return "";
+	}
+}
+function escapeTemplate(text) {
+	return text.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+function normalizeSelector(selector) {
+	return selector.replace(/\s+/g, " ").trim();
+}
+/** The subject of a selector = its last compound (after descendant combinators). */
+function lastCompound(selector) {
+	const parts = splitTopLevel(selector, DESCENDANT_COMBINATORS).map((part) => part.trim()).filter((part) => part.length > 0);
+	return parts.length > 0 ? parts[parts.length - 1] : selector;
+}
+/** Split on any of `seps` at bracket/paren depth 0. */
+function splitTopLevel(input, seps) {
+	const parts = [];
+	let depth = 0;
+	let current = "";
+	for (const char of input) {
+		if (char === "(" || char === "[") depth++;
+		else if (char === ")" || char === "]") depth = Math.max(0, depth - 1);
+		if (depth === 0 && seps.includes(char)) {
+			parts.push(current);
+			current = "";
+		} else current += char;
+	}
+	parts.push(current);
+	return parts;
+}
+//#endregion
+//#region src/imports.ts
+/**
+* Collects import specifiers needed by generated code and renders them as
+* `import` statements. Deduplicates and sorts for deterministic output.
+*/
+var ImportManager = class {
+	named = /* @__PURE__ */ new Map();
+	defaults = /* @__PURE__ */ new Map();
+	/** Require `import { <imported> as <local> } from "<module>"`. */
+	addNamed(module, imported, local = imported) {
+		let entry = this.named.get(module);
+		if (!entry) {
+			entry = /* @__PURE__ */ new Map();
+			this.named.set(module, entry);
+		}
+		entry.set(local, imported);
+	}
+	/** Require `import <local> from "<module>"`. */
+	addDefault(module, local) {
+		this.defaults.set(module, local);
+	}
+	isEmpty() {
+		return this.named.size === 0 && this.defaults.size === 0;
+	}
+	/** Render one import statement per module, sorted by module specifier. */
+	render() {
+		const modules = [.../* @__PURE__ */ new Set([...this.named.keys(), ...this.defaults.keys()])].sort();
+		const lines = [];
+		for (const module of modules) {
+			const clauses = [];
+			const defaultLocal = this.defaults.get(module);
+			if (defaultLocal) clauses.push(defaultLocal);
+			const named = this.named.get(module);
+			if (named && named.size > 0) {
+				const specifiers = [...named.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([local, imported]) => local === imported ? imported : `${imported} as ${local}`);
+				clauses.push(`{ ${specifiers.join(", ")} }`);
+			}
+			lines.push(`import ${clauses.join(", ")} from ${JSON.stringify(module)};`);
+		}
+		return lines.join("\n");
+	}
+};
+//#endregion
+export { ImportManager, buildPlaceholderCss, cast, cssPropToCamel, cssToVeStyle, globalRules, isEmptyObject, keyframesToVe, parseScss, placeholderToken, serializeVe, veArray, veBoolean, veNumber, veObject, veRaw, veString };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@omnimod/plugin-utils",
+  "version": "0.1.0",
+  "description": "Helpers for authoring omnimod plugins: AST matchers, CSS-in-JS parsing, import management.",
+  "keywords": [
+    "codemod",
+    "css-in-js",
+    "omnimod-plugin",
+    "postcss",
+    "vanilla-extract"
+  ],
+  "homepage": "https://salnika.github.io/omnimod/",
+  "bugs": "https://github.com/salnika/omnimod/issues",
+  "license": "MIT",
+  "author": "salnika",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/salnika/omnimod.git",
+    "directory": "packages/plugin-utils"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "postcss": "^8.5.16",
+    "postcss-scss": "^4.0.9",
+    "@omnimod/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.2",
+    "vite-plus": "0.2.2"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}