@weapp-tailwindcss/css-compat 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 ice breaker
+
+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

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @weapp-tailwindcss/css-compat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> English | [简体中文](./README.zh-CN.md)
+
+A framework-independent CSS cascade layer compiler. Version `0.1.0` provides layer registration, ordered compilation and source-aware diagnostics. Generator, scanner, runtime, selector/value transforms and Tailwind defaults remain in their adapters.
+
+## Install and exports
+
+```sh
+pnpm add -D @weapp-tailwindcss/css-compat postcss
+```
+
+Requires Node `^22.18.0 || >=24.11.0` and PostCSS `^8.5.29`. All four entrypoints ship ESM/CJS and matching declarations:
+
+- Root and `/layers`: `compileCascadeLayers`, `createCascadeLayersPlugin` and options.
+- `/diagnostics`: diagnostic types and `CascadeLayerError`.
+- `/legacy`: `consumeCascadeLayers`, preserving the existing anchor algorithm.
+
+## AST API
+
+```ts
+import { compileCascadeLayers } from '@weapp-tailwindcss/css-compat/layers'
+import postcss from 'postcss'
+
+const root = postcss.parse(css, { from: 'input.css' })
+const result = compileCascadeLayers(root, {
+  mode: 'ordered',
+  onConflict: 'warning',
+  inputStage: 'native',
+})
+console.log(result.root.toString(), result.diagnostics)
+```
+
+`mode` is required. `ordered` mutates and returns the same Root only after all checks pass. Errors throw `CascadeLayerError` with diagnostics and leave the input content, structure and node identities intact. `preserve` returns the original Root with no diagnostics, suitable for targets supporting native layers.
+
+`onConflict` defaults to `warning`; `error` rejects conservative diagnostics as well. `inputStage` defaults to `native`. Explicitly polyfilled input is rejected by ordered mode. Flattened CSS without provenance cannot recover layer semantics; author `:not(...)` selectors are retained without guessing their origin.
+
+## PostCSS pipeline
+
+```ts
+import { createCascadeLayersPlugin } from '@weapp-tailwindcss/css-compat'
+import postcss from 'postcss'
+
+const result = await postcss([
+  createCascadeLayersPlugin({ mode: 'ordered', onConflict: 'error' }),
+]).process(css, { from: 'input.css', to: 'output.css', map: { inline: false } })
+```
+
+Complete generation, import expansion, preprocessor conditionals and CSS nesting before ordered compilation. Put the plugin after those processors; it runs in `OnceExit`. Diagnostics become PostCSS warnings with a stable `code` and the full `diagnostic` attached. Standard PostCSS processing retains from/to/map and result messages.
+
+Variable safety analysis needs the original variable scope and layer information. Selector/value transforms can change specificity or introduce overrides; finish them before analyzing the final selectors. Merge inputs before compilation instead of flattening separate fragments and concatenating them.
+
+## Ordered contract and limits
+
+| Capability | Behavior |
+| --- | --- |
+| Named, repeated, dotted, nested, anonymous and escaped layers | First registration determines sibling order; anonymous identities never merge with author names |
+| Normal declarations | Child layers precede direct parent declarations; later layers win; unlayered declarations have highest priority |
+| Important declarations | Layer priority reverses; unlayered priority is lowest; fallback order within a layer stays intact |
+| Conditions and source maps | Wrappers and sources are retained; conditional first registration is diagnosed |
+| Descriptors | Preserved whole, once; cross-layer duplicate or uncertain identities are diagnosed |
+| Reprocessing | No-layer input is retained; Root reuse, serialization and processor reuse are stable |
+| Different specificity across layers | Potential inversions are diagnosed; ordering cannot emulate arbitrary cascade specificity |
+
+Normal and important declarations are analyzed separately, including selector lists. Property names are tokenizer-decoded while custom properties remain case-sensitive. Aliases and shorthand longhands share property identities. Logical/physical overlap, reset shorthands and unknown properties receive conservative treatment. Selector intersection and mutually exclusive conditions are not proven, so diagnostics may include false positives.
+
+Any remaining `@import`, `revert-layer`, nesting, invalid layer names, unconsumed preprocessor conditionals and explicitly polyfilled input always fail ordered mode, even with `onConflict: 'warning'`. Matching text inside strings and URLs is not interpreted as syntax. Independent whitespace around dotted layer separators is invalid; comments and escape-terminating whitespace are supported.
+
+## Diagnostics
+
+Diagnostics contain `code`, `severity`, `message`, `suggestion`, available source file/line/column and optional `related`, `layer`, `selector` and `property`. Nodes without source metadata do not get invented positions.
+
+| Code | Meaning |
+| --- | --- |
+| `LAYER_OPTIONS` | Invalid API options |
+| `LAYER_INPUT_STAGE` | Explicitly polyfilled input |
+| `LAYER_IMPORT` | Remaining import or invalid prologue location |
+| `LAYER_REVERT` | Unsupported revert-layer |
+| `LAYER_NESTING` | Remaining nesting or invalid declaration location |
+| `LAYER_NAME` | Invalid layer name/list |
+| `LAYER_PREPROCESSOR` | Unconsumed conditional compilation |
+| `LAYER_CONDITIONAL_ORDER` | Conditional first layer registration |
+| `LAYER_SPECIFICITY` | Potential cross-layer specificity inversion |
+| `LAYER_SELECTOR_UNKNOWN` | Selector cannot be reliably analyzed |
+| `LAYER_DESCRIPTOR_ORDER` | Cross-layer descriptor semantics need validation |
+| `LAYER_WRAPPER_SEMANTICS` | Unknown/scoping wrapper equivalence cannot be proven |
+
+## Scope and migration
+
+One Root represents one merged cascade scope. Merge using the actual import/build graph. Isolated components, independent subpackages and different targets require separate compilation. The caller owns graph relationships, caching and HMR invalidation; every compiler call owns independent state.
+
+`@weapp-tailwindcss/postcss/transform` continues re-exporting `consumeCascadeLayers(root)` from `/legacy`, including its existing limitations. The new API does not switch the published Tailwind layer defaults. Tailwind preflight/theme/components markers and Panda codec/recipes/runtime stay with their adapters.
+
+For Panda 2.1.2, disable generator polyfilling and pass generated CSS to this public plugin. Isolated tarball tests exercise real generated CSS without changing the Panda repository. Selector, variable, unit and color compatibility are follow-up work.
+
+## Verification
+
+```sh
+pnpm --filter @weapp-tailwindcss/css-compat build
+pnpm --filter @weapp-tailwindcss/css-compat test
+pnpm --filter @weapp-tailwindcss/css-compat typecheck
+pnpm --filter @weapp-tailwindcss/css-compat properties:check
+pnpm --filter @weapp-tailwindcss/css-compat test:package
+pnpm --filter @weapp-tailwindcss/css-compat test:consumers
+pnpm --filter @weapp-tailwindcss/css-compat test:browser
+pnpm --filter @weapp-tailwindcss/css-compat bench
+```
+
+Consumer tests require this checkout's PostCSS and generation-engine dependency builds. Browser tests require the installed Playwright version's Chromium, Firefox and WebKit binaries and fail if unavailable. Each engine runs headlessly and releases its browser/context/page. Package/browser evidence does not constitute WeChat or device acceptance. The compact property table is generated from pinned `mdn-data@2.37.2` (CC0-1.0) with explicit shorthand corrections; regenerate with `properties:generate`.

package/README.zh-CN.md

@@ -0,0 +1,106 @@
+# @weapp-tailwindcss/css-compat
+
+> [English](./README.md) | 简体中文
+
+框架无关的 CSS layer 兼容内核。首期版本为 `0.1.0`，只提供 layer 注册、顺序编译和定位诊断；不生成 class，不转换 runtime，不扫描文件，也不注入 Tailwind 默认值。
+
+## 安装与入口
+
+```sh
+pnpm add -D @weapp-tailwindcss/css-compat postcss
+```
+
+支持 Node `^22.18.0 || >=24.11.0`、PostCSS `^8.5.29`。根入口和 `/layers` 提供编译器与插件，`/diagnostics` 提供诊断类型及 `CascadeLayerError`，`/legacy` 提供旧 anchor 算法。每个入口均有 ESM/CJS 及对应声明。
+
+## AST API
+
+```ts
+import { compileCascadeLayers } from '@weapp-tailwindcss/css-compat/layers'
+import postcss from 'postcss'
+
+const root = postcss.parse(css, { from: 'input.css' })
+const result = compileCascadeLayers(root, {
+  mode: 'ordered',
+  onConflict: 'warning',
+  inputStage: 'native',
+})
+console.log(result.root.toString(), result.diagnostics)
+```
+
+`mode` 必填。`ordered` 在全部输入检查和冲突分析完成后原地修改 Root，返回同一个 Root 与诊断数组；失败抛出携带诊断的 `CascadeLayerError`，原始节点身份、结构和内容均不变。`preserve` 原样返回，适合支持原生 layer 的 Web 目标。`onConflict` 默认 `warning`，设为 `error` 时保守诊断也阻止编译。
+
+`inputStage` 默认 `native`；明确知道上游已经 polyfill 的输入应传 `polyfilled`，ordered 会拒绝它。未提供来源信息的已展平 CSS 无法恢复层语义；内核不会根据 `:not(...)` 的形状猜测来源，也不会清理作者选择器。
+
+## PostCSS 插件与顺序
+
+```ts
+import { createCascadeLayersPlugin } from '@weapp-tailwindcss/css-compat'
+import postcss from 'postcss'
+
+const result = await postcss([
+  // 在此之前完成生成器、import、条件编译及 nesting 展开。
+  createCascadeLayersPlugin({ mode: 'ordered', onConflict: 'error' }),
+]).process(css, { from: 'input.css', to: 'output.css', map: { inline: false } })
+```
+
+插件在 `OnceExit` 编译；将它放在 import/nesting 等前置插件之后。诊断通过 PostCSS warnings 输出，warning 带稳定 `code` 与完整 `diagnostic`。字符串处理使用 PostCSS 原生 `process`，保留 from/to/map/result messages。
+
+变量安全分析必须在原变量作用域与 layer 信息仍存在时进行。selector/value 转换可能改变权重或引入覆盖，调用者应先完成这些变换，再对最终选择器运行 ordered；不要把生成的两段 CSS 分别展平后再拼接。
+
+## 顺序兼容契约
+
+| 能力 | 行为 |
+| --- | --- |
+| 命名、重复、点分、嵌套、匿名、转义层 | 首次注册确定顺序；匿名身份不与作者名称合并 |
+| 普通声明 | 子层在父层直接声明之前，较晚层优先，未分层最高 |
+| important | 层优先级反转，未分层最低；同层 fallback 保持源顺序 |
+| 条件与 source map | 保留 wrapper 和来源；条件内首次注册产生诊断 |
+| descriptor | 完整保留，不拆分、不重复；跨层同名或身份不明的定义产生保守诊断 |
+| 无 layer、重复处理 | 不重排无 layer 输入；同 Root、序列化重读与处理器复用稳定 |
+| 跨层不同 specificity | 潜在冲突诊断；顺序展开不能等价模拟任意 CSS cascade |
+
+普通和 important 分别分析属性及 selector list 的权重倒置。属性名通过 tokenizer 解码，自定义属性继续区分大小写；别名归一后简写展开长写，逻辑/物理属性、reset shorthand 与未知属性保守处理。选择器是否相交、条件是否互斥不会被静态证明，因此诊断可能包含保守误报；strict 适用于愿意调整这类输入的消费者。
+
+任何未展开的 import、`revert-layer`、nesting、非法层名、未消费的条件编译控制注释和明确 polyfilled 的输入始终报错；这些输入不能靠将 onConflict 改为 warning 放行。字符串和 URL 中的同名字样不被当作语法。
+
+## 诊断
+
+诊断包含 `code`、`severity`、`message`、`suggestion`、`source`，以及可用的 `related`、`layer`、`selector`、`property`。source 包含可用的 file/line/column，人工创建且没有 source 的节点不会伪造位置。
+
+| code | 含义 |
+| --- | --- |
+| `LAYER_OPTIONS` | API 选项非法 |
+| `LAYER_INPUT_STAGE` | 来源明确已被 polyfill |
+| `LAYER_IMPORT` | 未展开 import 或不合法的 prologue 位置 |
+| `LAYER_REVERT` | 输入包含 revert-layer |
+| `LAYER_NESTING` | 尚未展开的 nesting 或不合法声明位置 |
+| `LAYER_NAME` | 层名或声明列表非法 |
+| `LAYER_PREPROCESSOR` | 未消费条件编译控制注释 |
+| `LAYER_CONDITIONAL_ORDER` | 条件中的首次层注册 |
+| `LAYER_SPECIFICITY` | 跨层潜在权重倒置 |
+| `LAYER_SELECTOR_UNKNOWN` | 无法可靠分析的选择器 |
+| `LAYER_DESCRIPTOR_ORDER` | 跨层同名 descriptor 需要验证 |
+| `LAYER_WRAPPER_SEMANTICS` | 不可证明等价的作用域/未知包装规则 |
+
+## 作用域与迁移
+
+一个 Root 只代表一个已合并的级联作用域。按真实 import/build graph 合并输入后再编译；app/page/component 样式隔离、独立分包和多目标分别建立模型。调用者拥有图关系、HMR 失效和缓存，内核每次调用独立持有状态。
+
+现有 `@weapp-tailwindcss/postcss/transform` 的 `consumeCascadeLayers(root)` 转导出 `/legacy`，保持旧 anchor 行为，包括原来的语义限制。新 ordered API 不替换线上默认策略；Web 默认为原生层保留。Tailwind preflight/theme/components 标记、Panda codec/recipe/runtime 继续由对应 adapter 负责。
+
+Panda 2.1.2 应关闭生成器 polyfill，将生成 CSS 交给本包的公开插件；本期提供隔离 tarball 消费测试，不修改 Panda 仓库。后续再逐项提取 selector、变量、单位和颜色能力。
+
+## 验证
+
+```sh
+pnpm --filter @weapp-tailwindcss/css-compat build
+pnpm --filter @weapp-tailwindcss/css-compat test
+pnpm --filter @weapp-tailwindcss/css-compat typecheck
+pnpm --filter @weapp-tailwindcss/css-compat properties:check
+pnpm --filter @weapp-tailwindcss/css-compat test:package
+pnpm --filter @weapp-tailwindcss/css-compat test:consumers
+pnpm --filter @weapp-tailwindcss/css-compat test:browser
+pnpm --filter @weapp-tailwindcss/css-compat bench
+```
+
+消费测试先构建本 worktree 的 PostCSS 及生成引擎依赖；浏览器测试需要当前 Playwright 对应的 Chromium、Firefox、WebKit 二进制，缺失时失败，不静默 skip。三个引擎依次后台运行，均定向释放 browser/context/page。包级证据不代表真实微信或全平台验收。属性映射由固定 `mdn-data@2.37.2`（CC0-1.0）生成，运行 `properties:generate` 更新。

package/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,126 @@
+本包构建产物包含以下依赖的代码；精简属性表来自 mdn-data@2.37.2（CC0-1.0）。
+MDN 来源：https://github.com/mdn/data
+
+
+@csstools/css-tokenizer@4.0.2 (MIT)
+
+The MIT License (MIT)
+
+Copyright 2022 Romain Menke, Antonio Laguna <antonio@laguna.es>
+
+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.
+
+
+@csstools/selector-specificity@6.0.1 (MIT-0)
+
+MIT No Attribution (MIT-0)
+
+Copyright © CSSTools Contributors
+
+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.
+
+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.
+
+
+postcss-selector-parser@7.1.6 (MIT)
+
+Copyright (c) Ben Briggs <beneb.info@gmail.com> (http://beneb.info)
+
+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.
+
+
+cssesc@3.0.0 (MIT)
+
+Copyright Mathias Bynens <https://mathiasbynens.be/>
+
+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.
+
+
+util-deprecate@1.0.2 (MIT)
+
+(The MIT License)
+
+Copyright (c) 2014 Nathan Rajlich <nathan@tootallnate.net>
+
+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/dist/diagnostics.cjs

@@ -0,0 +1,13 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/diagnostics.ts
+/** 编译失败的诊断集合；失败时调用者的 Root 保持完整。 */
+var CascadeLayerError = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(diagnostics.map((item) => `[${item.code}] ${item.message}`).join("\n"));
+		this.name = "CascadeLayerError";
+		this.diagnostics = [...diagnostics];
+	}
+};
+//#endregion
+exports.CascadeLayerError = CascadeLayerError;

package/dist/diagnostics.d.cts

@@ -0,0 +1,24 @@
+//#region src/diagnostics.d.ts
+export type CascadeLayerDiagnosticCode = 'LAYER_OPTIONS' | 'LAYER_INPUT_STAGE' | 'LAYER_IMPORT' | 'LAYER_REVERT' | 'LAYER_NESTING' | 'LAYER_NAME' | 'LAYER_PREPROCESSOR' | 'LAYER_CONDITIONAL_ORDER' | 'LAYER_SPECIFICITY' | 'LAYER_SELECTOR_UNKNOWN' | 'LAYER_DESCRIPTOR_ORDER' | 'LAYER_WRAPPER_SEMANTICS';
+export interface CascadeLayerSource {
+  file?: string | undefined;
+  line?: number | undefined;
+  column?: number | undefined;
+}
+export interface CascadeLayerDiagnostic {
+  code: CascadeLayerDiagnosticCode;
+  severity: 'warning' | 'error';
+  message: string;
+  suggestion: string;
+  source: CascadeLayerSource;
+  related?: CascadeLayerSource | undefined;
+  layer?: string | undefined;
+  selector?: string | undefined;
+  property?: string | undefined;
+}
+/** 编译失败的诊断集合；失败时调用者的 Root 保持完整。 */
+export declare class CascadeLayerError extends Error {
+  readonly diagnostics: readonly CascadeLayerDiagnostic[];
+  constructor(diagnostics: readonly CascadeLayerDiagnostic[]);
+}
+//#endregion

package/dist/diagnostics.d.mts

@@ -0,0 +1,24 @@
+//#region src/diagnostics.d.ts
+export type CascadeLayerDiagnosticCode = 'LAYER_OPTIONS' | 'LAYER_INPUT_STAGE' | 'LAYER_IMPORT' | 'LAYER_REVERT' | 'LAYER_NESTING' | 'LAYER_NAME' | 'LAYER_PREPROCESSOR' | 'LAYER_CONDITIONAL_ORDER' | 'LAYER_SPECIFICITY' | 'LAYER_SELECTOR_UNKNOWN' | 'LAYER_DESCRIPTOR_ORDER' | 'LAYER_WRAPPER_SEMANTICS';
+export interface CascadeLayerSource {
+  file?: string | undefined;
+  line?: number | undefined;
+  column?: number | undefined;
+}
+export interface CascadeLayerDiagnostic {
+  code: CascadeLayerDiagnosticCode;
+  severity: 'warning' | 'error';
+  message: string;
+  suggestion: string;
+  source: CascadeLayerSource;
+  related?: CascadeLayerSource | undefined;
+  layer?: string | undefined;
+  selector?: string | undefined;
+  property?: string | undefined;
+}
+/** 编译失败的诊断集合；失败时调用者的 Root 保持完整。 */
+export declare class CascadeLayerError extends Error {
+  readonly diagnostics: readonly CascadeLayerDiagnostic[];
+  constructor(diagnostics: readonly CascadeLayerDiagnostic[]);
+}
+//#endregion

package/dist/diagnostics.mjs

@@ -0,0 +1,12 @@
+//#region src/diagnostics.ts
+/** 编译失败的诊断集合；失败时调用者的 Root 保持完整。 */
+var CascadeLayerError = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(diagnostics.map((item) => `[${item.code}] ${item.message}`).join("\n"));
+		this.name = "CascadeLayerError";
+		this.diagnostics = [...diagnostics];
+	}
+};
+//#endregion
+export { CascadeLayerError };

package/dist/index.cjs

@@ -0,0 +1,6 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_diagnostics = require("./diagnostics.cjs");
+const require_layers = require("./layers-CT2GtJgP.cjs");
+exports.CascadeLayerError = require_diagnostics.CascadeLayerError;
+exports.compileCascadeLayers = require_layers.compileCascadeLayers;
+exports.createCascadeLayersPlugin = require_layers.createCascadeLayersPlugin;

package/dist/index.d.cts

@@ -0,0 +1,3 @@
+import { CascadeLayerDiagnostic, CascadeLayerDiagnosticCode, CascadeLayerError, CascadeLayerSource } from "./diagnostics.cjs";
+import { CascadeLayerCompilation, CascadeLayerOptions, compileCascadeLayers, createCascadeLayersPlugin } from "./layers.cjs";
+export { type CascadeLayerCompilation, type CascadeLayerDiagnostic, type CascadeLayerDiagnosticCode, CascadeLayerError, type CascadeLayerOptions, type CascadeLayerSource, compileCascadeLayers, createCascadeLayersPlugin };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { CascadeLayerDiagnostic, CascadeLayerDiagnosticCode, CascadeLayerError, CascadeLayerSource } from "./diagnostics.mjs";
+import { CascadeLayerCompilation, CascadeLayerOptions, compileCascadeLayers, createCascadeLayersPlugin } from "./layers.mjs";
+export { type CascadeLayerCompilation, type CascadeLayerDiagnostic, type CascadeLayerDiagnosticCode, CascadeLayerError, type CascadeLayerOptions, type CascadeLayerSource, compileCascadeLayers, createCascadeLayersPlugin };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { n as createCascadeLayersPlugin, t as compileCascadeLayers } from "./layers-D0OJtr2q.mjs";
+import { CascadeLayerError } from "./diagnostics.mjs";
+export { CascadeLayerError, compileCascadeLayers, createCascadeLayersPlugin };