@zealakit/css-doctor-binding 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zealamic
+
+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,48 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# @zealakit/css-doctor-binding
+
+**Native NAPI-RS bridge for the css-doctor LightningCSS engine.** 
+
+[English](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README.md) | [Tiếng Việt](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README_VI.md) | [简体中文](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README_CN.md)
+
+</div>
+
+---
+
+![css doctor](https://github.com/zealakit/css-doctor/blob/main/assets/images/css-doctor.jpg)
+
+## Installation
+
+```bash
+pnpm add @zealakit/css-doctor-binding
+```
+
+## Usage
+
+```ts
+import { analyzeCss, optimizeCss } from "@zealakit/css-doctor-binding";
+
+const analysis = analyzeCss(".card { color: red; }");
+
+const result = optimizeCss({
+  cssContent: ".card { color: red; } :root { --brand: red; }",
+  pageUsage: { home: ["card"] },
+  pageCoverage: { enabled: true, minPageRatio: 0.5 },
+  sizeBudget: { enabled: true, maxChunkSize: 40 * 1024, isolateVariables: true },
+  minify: true,
+});
+
+console.log(analysis.stats.selectorCount);
+console.log(result.chunks);
+```
+
+## Safety and limitations
+
+- Prebuilt binaries cover darwin-arm64, darwin-x64, linux-x64-gnu, linux-x64-musl, and win32-x64-msvc.
+- The native API is low-level; prefer @zealakit/css-doctor-vite, next, rsbuild, nuxt, or remix for application builds.
+- Never edit generated index.js, index.d.ts, index.d.cts, or *.node files by hand.
+
+## Full documentation
+
+Project README: [English](https://github.com/zealakit/css-doctor/blob/main/README.md) | [Tiếng Việt](https://github.com/zealakit/css-doctor/blob/main/README_VI.md) | [简体中文](https://github.com/zealakit/css-doctor/blob/main/README_CN.md)

package/README_CN.md

@@ -0,0 +1,48 @@
+<div align="center">
+
+# @zealakit/css-doctor-binding
+
+**css-doctor LightningCSS 引擎的原生 NAPI-RS 桥接层。**
+
+[English](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README.md) | [Tiếng Việt](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README_VI.md) | [简体中文](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README_CN.md)
+
+</div>
+
+---
+
+![css doctor](https://github.com/zealakit/css-doctor/blob/main/assets/images/css-doctor.jpg)
+
+## 安装
+
+```bash
+pnpm add @zealakit/css-doctor-binding
+```
+
+## 使用
+
+```ts
+import { analyzeCss, optimizeCss } from "@zealakit/css-doctor-binding";
+
+const analysis = analyzeCss(".card { color: red; }");
+
+const result = optimizeCss({
+  cssContent: ".card { color: red; } :root { --brand: red; }",
+  pageUsage: { home: ["card"] },
+  pageCoverage: { enabled: true, minPageRatio: 0.5 },
+  sizeBudget: { enabled: true, maxChunkSize: 40 * 1024, isolateVariables: true },
+  minify: true,
+});
+
+console.log(analysis.stats.selectorCount);
+console.log(result.chunks);
+```
+
+## 安全与限制
+
+- 预构建二进制支持 darwin-arm64、darwin-x64、linux-x64-gnu、linux-x64-musl 和 win32-x64-msvc。
+- 原生 API 属于底层接口；应用构建推荐使用 @zealakit/css-doctor-vite、next、rsbuild、nuxt 或 remix。
+- 不要手动修改生成的 index.js、index.d.ts、index.d.cts 或 *.node。
+
+## 完整文档
+
+项目 README：[English](https://github.com/zealakit/css-doctor/blob/main/README.md) | [Tiếng Việt](https://github.com/zealakit/css-doctor/blob/main/README_VI.md) | [简体中文](https://github.com/zealakit/css-doctor/blob/main/README_CN.md)

package/README_VI.md

@@ -0,0 +1,48 @@
+<div align="center">
+
+# @zealakit/css-doctor-binding
+
+**Cầu nối NAPI-RS native cho engine LightningCSS của css-doctor.**
+
+[English](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README.md) | [Tiếng Việt](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README_VI.md) | [简体中文](https://github.com/zealakit/css-doctor/blob/main/packages/binding/README_CN.md)
+
+</div>
+
+---
+
+![css doctor](https://github.com/zealakit/css-doctor/blob/main/assets/images/css-doctor.jpg)
+
+## Cài đặt
+
+```bash
+pnpm add @zealakit/css-doctor-binding
+```
+
+## Sử dụng
+
+```ts
+import { analyzeCss, optimizeCss } from "@zealakit/css-doctor-binding";
+
+const analysis = analyzeCss(".card { color: red; }");
+
+const result = optimizeCss({
+  cssContent: ".card { color: red; } :root { --brand: red; }",
+  pageUsage: { home: ["card"] },
+  pageCoverage: { enabled: true, minPageRatio: 0.5 },
+  sizeBudget: { enabled: true, maxChunkSize: 40 * 1024, isolateVariables: true },
+  minify: true,
+});
+
+console.log(analysis.stats.selectorCount);
+console.log(result.chunks);
+```
+
+## An toàn và giới hạn
+
+- Binary dựng sẵn hỗ trợ darwin-arm64, darwin-x64, linux-x64-gnu, linux-x64-musl và win32-x64-msvc.
+- API native là low-level; nên dùng @zealakit/css-doctor-vite, next, rsbuild, nuxt hoặc remix cho ứng dụng.
+- Không chỉnh tay index.js, index.d.ts, index.d.cts hoặc *.node đã generate.
+
+## Tài liệu đầy đủ
+
+README dự án: [English](https://github.com/zealakit/css-doctor/blob/main/README.md) | [Tiếng Việt](https://github.com/zealakit/css-doctor/blob/main/README_VI.md) | [简体中文](https://github.com/zealakit/css-doctor/blob/main/README_CN.md)

package/index.d.ts

@@ -0,0 +1,533 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** The kind of a simple selector. */
+export const enum JsSelectorKind {
+  /** A class selector such as `.button`. */
+  Class = 'class',
+  /** An ID selector such as `#app`. */
+  Id = 'id',
+  /** A type/tag selector such as `section`. */
+  Tag = 'tag',
+  /** An attribute selector such as `[data-state="open"]`. */
+  Attribute = 'attribute',
+  /** A pseudo-class such as `:hover`. */
+  PseudoClass = 'pseudo_class',
+  /** A pseudo-element such as `::before`. */
+  PseudoElement = 'pseudo_element',
+  /** The universal selector `*`. */
+  Universal = 'universal',
+  /** The CSS nesting selector `&`. */
+  Nesting = 'nesting'
+}
+/** Decoded CSS specificity. */
+export interface JsSpecificity {
+  /** Number of ID selectors. */
+  ids: number
+  /** Number of class, attribute and pseudo-class selectors. */
+  classes: number
+  /** Number of type and pseudo-element selectors. */
+  types: number
+}
+/** A 1-based source location. */
+export interface JsSourceLocation {
+  /** 1-based line number. */
+  line: number
+  /** 1-based column number. */
+  column: number
+}
+/** A non-fatal parser warning. */
+export interface JsAnalysisWarning {
+  /** Human-readable description of the problem. */
+  message: string
+  /** Location of the problem, when known. */
+  location?: JsSourceLocation
+}
+/** A selector extracted from a style rule. */
+export interface JsSelectorInfo {
+  /** Normalized selector text. */
+  raw: string
+  /** Simple-selector kinds present in the selector. */
+  kinds: Array<JsSelectorKind>
+  /** Class names without the leading dot. */
+  classes: Array<string>
+  /** ID names without the leading hash. */
+  ids: Array<string>
+  /** Local type/tag names. */
+  tags: Array<string>
+  /** Local attribute names. */
+  attributes: Array<string>
+  /** Pseudo-class names without the leading colon or arguments. */
+  pseudoClasses: Array<string>
+  /** Pseudo-element names without the leading `::` or arguments. */
+  pseudoElements: Array<string>
+  /** Tree combinators present (`" "`, `">"`, `"+"`, `"~"`). */
+  combinators: Array<string>
+  /** Decoded specificity. */
+  specificity: JsSpecificity
+  /** Index into `CssAnalysisResult.rules`. */
+  ruleIndex: number
+  /** Number of enclosing style rules. */
+  nestingDepth: number
+}
+/** A style rule and its selectors. */
+export interface JsStyleRuleInfo {
+  /** Index of the rule in `CssAnalysisResult.rules`. */
+  index: number
+  /** Index of the enclosing style rule, when nested. */
+  parentRuleIndex?: number
+  /** Indices into `CssAnalysisResult.selectors`. */
+  selectorIndices: Array<number>
+  /** Number of normal declarations. */
+  declarationCount: number
+  /** Number of `!important` declarations. */
+  importantDeclarationCount: number
+  /** Number of enclosing style rules. */
+  nestingDepth: number
+  /** Location of the rule in the source. */
+  location: JsSourceLocation
+}
+/** Aggregate counters for an analysis run. */
+export interface JsAnalysisStats {
+  /** Number of style rules. */
+  ruleCount: number
+  /** Number of selectors. */
+  selectorCount: number
+  /** Total number of normal declarations. */
+  declarationCount: number
+  /** Total number of `!important` declarations. */
+  importantDeclarationCount: number
+  /** Number of distinct class names. */
+  uniqueClassCount: number
+  /** Number of distinct ID names. */
+  uniqueIdCount: number
+  /** Number of distinct type/tag names. */
+  uniqueTagCount: number
+  /** Number of distinct attribute names. */
+  uniqueAttributeCount: number
+  /** Deepest style-rule nesting observed. */
+  maxNestingDepth: number
+  /** Number of parser warnings. */
+  warningCount: number
+}
+/** The complete result of analyzing a stylesheet. */
+export interface JsCssAnalysisResult {
+  /** All selectors in document order. */
+  selectors: Array<JsSelectorInfo>
+  /** All style rules in document order. */
+  rules: Array<JsStyleRuleInfo>
+  /** Aggregate counters. */
+  stats: JsAnalysisStats
+  /** Recoverable parser warnings. */
+  warnings: Array<JsAnalysisWarning>
+}
+/**
+ * Analyzes a CSS string synchronously.
+ *
+ * # Errors
+ *
+ * Rejects with a JavaScript `Error` when the stylesheet cannot be parsed at
+ * all. Recoverable syntax errors are returned as `warnings` instead.
+ */
+export declare function analyzeCss(cssContent: string): JsCssAnalysisResult
+/**
+ * Analyzes a CSS string on the libuv thread pool and returns a `Promise`.
+ *
+ * This is the preferred entry point for large stylesheets because it does not
+ * block the Node.js event loop.
+ *
+ * # Errors
+ *
+ * Rejects with a JavaScript `Error` when the stylesheet cannot be parsed.
+ */
+export declare function analyzeCssAsync(cssContent: string): Promise<JsCssAnalysisResult>
+/**
+ * Analyzes a CSS string and returns the result as a JSON string.
+ *
+ * The JSON shape is identical to the object returned by `analyzeCss`.
+ *
+ * # Errors
+ *
+ * Rejects with a JavaScript `Error` when parsing or serialization fails.
+ */
+export declare function analyzeCssJson(cssContent: string): string
+/** Configuration for page-coverage chunk splitting. */
+export interface JsChunkConfig {
+  /**
+   * Minimum share of pages that must use a rule before it is considered
+   * common. Range: 0.0..=1.0.
+   */
+  minPageRatio: number
+  /** Selectors or class names that should always stay in the common chunk. */
+  forceCommonSelectors: Array<string>
+  /** Minify serialized CSS. Defaults to `true`. */
+  minify?: boolean
+}
+/** Input for [`split_css_by_pages`]. */
+export interface JsSplitInput {
+  /** Original CSS source. */
+  cssContent: string
+  /** Page/route name to class names used by that page. */
+  pageUsage: Record<string, Array<string>>
+  /** Splitting configuration. */
+  config: JsChunkConfig
+}
+/** Usage information for one selector. */
+export interface JsSelectorStat {
+  /** Original selector text. */
+  selector: string
+  /** Matched class occurrences across pages. */
+  totalOccurrences: number
+  /** Number of pages using the selector. */
+  pageCount: number
+  /** Fraction of pages using the selector (0..1). */
+  coverageRatio: number
+  /** `common`, `dead`, or `page:<name>[,<name>...]`. */
+  targetChunk: string
+}
+/** Result of page-coverage chunk splitting. */
+export interface JsSplitOutput {
+  /** CSS shared by pages reaching the coverage threshold, plus global rules. */
+  commonCss: string
+  /** Page name to page-specific CSS. */
+  pageChunks: Record<string, string>
+  /** Per-selector usage matrix. */
+  stats: Array<JsSelectorStat>
+  /** Number of dead selector occurrences removed. */
+  deadCodeCount: number
+}
+/**
+ * Splits a stylesheet into common and page-specific CSS chunks.
+ *
+ * # Errors
+ *
+ * Rejects with a JavaScript `Error` when the configuration is invalid or the
+ * stylesheet/AST cannot be processed.
+ */
+export declare function splitCssByPages(input: JsSplitInput): JsSplitOutput
+/** Configuration for the semantic page-coverage tier. */
+export interface JsPageCoverageConfig {
+  /** Enable page-coverage splitting. Defaults to `true`. */
+  enabled?: boolean
+  /** Minimum page coverage for common rules. Defaults to `0.5`. */
+  minPageRatio?: number
+  /** Selectors or classes that always stay in the common chunk. */
+  forceCommon?: Array<string>
+}
+/** Configuration for the physical size-budget tier. */
+export interface JsSizeBudgetConfig {
+  /** Enable size-budget splitting. Defaults to `true`. */
+  enabled?: boolean
+  /** Maximum serialized bytes per body chunk. Defaults to 60 KiB. */
+  maxChunkSize?: number
+  /** Isolate CSS variables before splitting. Defaults to `true`. */
+  isolateVariables?: boolean
+}
+/** Input for [`optimize_css`]. */
+export interface JsPipelineInput {
+  /** Original CSS source. */
+  cssContent: string
+  /** Page/route name to class names used by that page. */
+  pageUsage: Record<string, Array<string>>
+  /** Optional tier 1 configuration. */
+  pageCoverage?: JsPageCoverageConfig
+  /** Optional tier 2 configuration. */
+  sizeBudget?: JsSizeBudgetConfig
+  /** Minify serialized CSS. Defaults to `true`. */
+  minify?: boolean
+}
+/** The stage that produced a pipeline chunk. */
+export const enum JsPipelineChunkKind {
+  /** Shared/common rules. */
+  Common = 'common',
+  /** Page-specific rules. */
+  Page = 'page',
+  /** Isolated CSS variables. */
+  Variables = 'variables',
+  /** A size-budget part. */
+  Part = 'part'
+}
+/** One CSS chunk emitted by the pipeline. */
+export interface JsChunkOutput {
+  /** Logical file stem, e.g. `common`, `page-home`, `common-vars`. */
+  name: string
+  /** Base chunk before physical splitting. */
+  sourceChunk: string
+  /** Serialized CSS. */
+  css: string
+  /** Stage/kind of this chunk. */
+  kind: JsPipelineChunkKind
+  /** Page that owns this chunk, when applicable. */
+  page?: string
+  /** Whether this chunk contains isolated CSS variables. */
+  variables: boolean
+  /** 1-based part index when produced by size splitting. */
+  part?: number
+  /** Serialized byte size. */
+  sizeBytes: number
+  /** True when an indivisible rule exceeds the budget. */
+  oversized: boolean
+  /** True when this chunk exists because of the size budget. */
+  splitDueToSize: boolean
+}
+/** Result of the two-tier optimization pipeline. */
+export interface JsPipelineOutput {
+  /** Final chunks in load order. */
+  chunks: Array<JsChunkOutput>
+  /** Selector usage matrix from tier 1. */
+  stats: Array<JsSelectorStat>
+  /** Dead selector occurrences removed by tier 1. */
+  deadCodeCount: number
+  /** Pages discovered from `page_usage`. */
+  pages: Array<string>
+  /** Whether page-coverage splitting actually ran. */
+  pageCoverageApplied: boolean
+  /** Whether size-budget processing was enabled. */
+  sizeBudgetApplied: boolean
+}
+/**
+ * Runs the two-tier CSS optimization pipeline.
+ *
+ * # Errors
+ *
+ * Rejects with a JavaScript `Error` when the configuration is invalid or the
+ * stylesheet/AST cannot be processed.
+ */
+export declare function optimizeCss(input: JsPipelineInput): JsPipelineOutput
+/** Combined pipeline output + optimization report from a single native run. */
+export interface JsOptimizeExplained {
+  pipeline: JsPipelineOutput
+  reportJson: string
+}
+/**
+ * Runs the optimization pipeline once and returns both chunks and a report.
+ *
+ * Prefer this over calling [`optimize_css`] and [`optimize_css_report`]
+ * separately to avoid double parsing/splitting.
+ *
+ * # Errors
+ *
+ * Rejects when the pipeline or report builder fails.
+ */
+export declare function optimizeCssExplained(input: JsPipelineInput, maxSelectorDecisions?: number | undefined | null): JsOptimizeExplained
+/**
+ * Runs the optimization pipeline and returns a versioned report JSON document
+ * that includes decisions, metrics, and chunk inventory.
+ *
+ * # Errors
+ *
+ * Rejects when the pipeline or report builder fails.
+ */
+export declare function optimizeCssReport(input: JsPipelineInput, maxSelectorDecisions?: number | undefined | null): string
+/** Lists built-in autofix rules as JSON. */
+export declare function listCssFixes(): string
+/** Autofix input. */
+export interface JsFixInput {
+  cssContent: string
+  filePath?: string
+  dryRun?: boolean
+  rules?: Array<string>
+  includeReview?: boolean
+}
+/**
+ * Plans or applies safe CSS autofixes. Returns a JSON `FixApplicationResult`.
+ *
+ * # Errors
+ *
+ * Rejects for parse/serialize failures or unsafe rule selection.
+ */
+export declare function applyCssFixes(input: JsFixInput): string
+/** Optional weights for CSS Health Score dimensions (must be >= 0). */
+export interface JsHealthWeights {
+  selectorComplexity?: number
+  duplicateRules?: number
+  cssSizeEfficiency?: number
+  deadCss?: number
+  variableConsistency?: number
+}
+/** Optional thresholds for CSS Health Score analyzers. */
+export interface JsHealthThresholds {
+  highSpecificityClasses?: number
+  highSpecificityIds?: number
+  deepCombinatorCount?: number
+  deepNestingDepth?: number
+  longSelectorTokenCount?: number
+  largeStylesheetBytes?: number
+  criticalStylesheetBytes?: number
+  heavyRuleDeclarations?: number
+  manySelectors?: number
+}
+/** Input for [`evaluate_css_health`]. */
+export interface JsHealthInput {
+  cssContent: string
+  filePath?: string
+  sizeBytes?: number
+  weights?: JsHealthWeights
+  thresholds?: JsHealthThresholds
+}
+/** One health diagnostic finding. */
+export interface JsHealthDiagnostic {
+  code: string
+  severity: string
+  category: string
+  message: string
+  filePath?: string
+  location?: JsSourceLocation
+  selector?: string
+  remediation: string
+  certainty: string
+}
+/** Score metadata for one health dimension. */
+export interface JsDimensionScore {
+  id: string
+  score?: number
+  weight: number
+  effectiveWeight: number
+  evaluated: boolean
+  issueCount: number
+  errorCount: number
+  warningCount: number
+  infoCount: number
+  diagnosticCodes: Array<string>
+  recommendations: Array<string>
+  note?: string
+}
+/** Aggregate counters for a health report. */
+export interface JsHealthScoreSummary {
+  files: number
+  rules: number
+  selectors: number
+  declarations: number
+  sizeBytes: number
+  errors: number
+  warnings: number
+  suggestions: number
+  analysisMs: number
+}
+/** Complete CSS Health Score report. */
+export interface JsHealthReport {
+  schemaVersion: number
+  overall: number
+  grade: string
+  status: string
+  dimensions: Array<JsDimensionScore>
+  summary: JsHealthScoreSummary
+  diagnostics: Array<JsHealthDiagnostic>
+  recommendations: Array<string>
+}
+/**
+ * Evaluates CSS Health Score for a single stylesheet.
+ *
+ * # Errors
+ *
+ * Rejects when configuration is invalid or CSS cannot be parsed.
+ */
+export declare function evaluateCssHealth(input: JsHealthInput): JsHealthReport
+/** One stylesheet entry for multi-file health evaluation. */
+export interface JsHealthFileInput {
+  cssContent: string
+  filePath?: string
+  sizeBytes?: number
+}
+/** Multi-file health evaluation input. */
+export interface JsHealthBatchInput {
+  files: Array<JsHealthFileInput>
+  weights?: JsHealthWeights
+  thresholds?: JsHealthThresholds
+}
+/**
+ * Evaluates and merges CSS Health Score across multiple stylesheets.
+ *
+ * # Errors
+ *
+ * Rejects when configuration is invalid or any stylesheet cannot be parsed.
+ */
+export declare function evaluateCssHealthBatch(input: JsHealthBatchInput): JsHealthReport
+/** File entry used when creating a baseline document. */
+export interface JsBaselineFileInput {
+  path: string
+  cssContent: string
+  sizeBytes?: number
+}
+/** Optional Git metadata for a baseline. */
+export interface JsBaselineGitMetadata {
+  commit?: string
+  branch?: string
+  dirty?: boolean
+}
+/** Optional project metadata for a baseline. */
+export interface JsBaselineProjectMetadata {
+  name?: string
+  root?: string
+}
+/** Input for [`create_baseline`]. */
+export interface JsBaselineCreateInput {
+  files: Array<JsBaselineFileInput>
+  toolVersion: string
+  createdAt?: string
+  patterns?: Array<string>
+  threshold?: number
+  project?: JsBaselineProjectMetadata
+  git?: JsBaselineGitMetadata
+  weights?: JsHealthWeights
+  thresholds?: JsHealthThresholds
+}
+/** Validation outcome for a baseline document. */
+export interface JsBaselineValidationResult {
+  status: string
+  message?: string
+}
+/** Comparison tolerances for regression detection. */
+export interface JsCompareOptions {
+  scoreTolerance?: number
+  sizeAbsoluteToleranceBytes?: number
+  sizeIncreasePercent?: number
+  countAbsoluteTolerance?: number
+  countIncreasePercent?: number
+}
+/** Minimum dimension score gate. */
+export interface JsMinDimensionScore {
+  id: string
+  minScore: number
+}
+/** Quality-gate configuration for regression comparison. */
+export interface JsQualityGateConfig {
+  minScore?: number
+  minDimensionScores?: Array<JsMinDimensionScore>
+  maxCssSize?: number
+  maxSizeIncreasePercent?: number
+  maxNewErrors?: number
+  maxNewWarnings?: number
+  failOnRegression?: boolean
+  failOnNewErrors?: boolean
+  failOnNewDiagnostics?: boolean
+}
+/**
+ * Creates a versioned baseline JSON document from CSS files.
+ *
+ * # Errors
+ *
+ * Rejects when configuration is invalid, CSS cannot be parsed, or
+ * serialization fails.
+ */
+export declare function createBaseline(input: JsBaselineCreateInput): string
+/**
+ * Validates a baseline JSON document.
+ *
+ * # Errors
+ *
+ * Rejects when the JSON cannot be parsed.
+ */
+export declare function validateBaseline(baselineJson: string, toolVersion: string): JsBaselineValidationResult
+/**
+ * Compares a stored baseline against a current baseline snapshot.
+ *
+ * Returns a versioned regression report as pretty JSON.
+ *
+ * # Errors
+ *
+ * Rejects when either document is invalid JSON or options are invalid.
+ */
+export declare function compareBaselines(baselineJson: string, currentJson: string, options?: JsCompareOptions | undefined | null, gates?: JsQualityGateConfig | undefined | null): string

package/index.js

@@ -0,0 +1,330 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'css-doctor-binding.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.android-arm64.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'css-doctor-binding.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'css-doctor-binding.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'css-doctor-binding.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'css-doctor-binding.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'css-doctor-binding.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./css-doctor-binding.darwin-universal.node')
+      } else {
+        nativeBinding = require('@zealakit/css-doctor-binding-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'css-doctor-binding.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.darwin-x64.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'css-doctor-binding.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'css-doctor-binding.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./css-doctor-binding.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@zealakit/css-doctor-binding-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'css-doctor-binding.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./css-doctor-binding.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@zealakit/css-doctor-binding-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'css-doctor-binding.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./css-doctor-binding.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@zealakit/css-doctor-binding-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { JsSelectorKind, analyzeCss, analyzeCssAsync, analyzeCssJson, splitCssByPages, JsPipelineChunkKind, optimizeCss, optimizeCssExplained, optimizeCssReport, listCssFixes, applyCssFixes, evaluateCssHealth, evaluateCssHealthBatch, createBaseline, validateBaseline, compareBaselines } = nativeBinding
+
+module.exports.JsSelectorKind = JsSelectorKind
+module.exports.analyzeCss = analyzeCss
+module.exports.analyzeCssAsync = analyzeCssAsync
+module.exports.analyzeCssJson = analyzeCssJson
+module.exports.splitCssByPages = splitCssByPages
+module.exports.JsPipelineChunkKind = JsPipelineChunkKind
+module.exports.optimizeCss = optimizeCss
+module.exports.optimizeCssExplained = optimizeCssExplained
+module.exports.optimizeCssReport = optimizeCssReport
+module.exports.listCssFixes = listCssFixes
+module.exports.applyCssFixes = applyCssFixes
+module.exports.evaluateCssHealth = evaluateCssHealth
+module.exports.evaluateCssHealthBatch = evaluateCssHealthBatch
+module.exports.createBaseline = createBaseline
+module.exports.validateBaseline = validateBaseline
+module.exports.compareBaselines = compareBaselines

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@zealakit/css-doctor-binding",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Native Node.js bindings for the css-doctor CSS analysis engine",
+  "keywords": [
+    "css",
+    "css-doctor",
+    "css-analysis",
+    "css-optimizer",
+    "dead-code-elimination",
+    "unused-css",
+    "purgecss",
+    "critical-css",
+    "css-splitting",
+    "page-coverage",
+    "lightningcss",
+    "native-addon",
+    "napi",
+    "napi-rs",
+    "rust",
+    "nodejs",
+    "performance",
+    "web-performance",
+    "stylesheet",
+    "frontend"
+  ],
+  "author": "nqhed - Huy Edward Nguyen",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zealakit/css-doctor.git",
+    "directory": "packages/binding"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "index.d.cts",
+    "*.node",
+    "README.md",
+    "README_VI.md",
+    "README_CN.md"
+  ],
+  "napi": {
+    "name": "css-doctor-binding",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@zealakit/css-doctor-binding-darwin-arm64": "1.1.0",
+    "@zealakit/css-doctor-binding-darwin-x64": "1.1.0",
+    "@zealakit/css-doctor-binding-linux-x64-gnu": "1.1.0",
+    "@zealakit/css-doctor-binding-linux-x64-musl": "1.1.0",
+    "@zealakit/css-doctor-binding-win32-x64-msvc": "1.1.0"
+  },
+  "bugs": {
+    "url": "https://github.com/zealakit/css-doctor/issues"
+  },
+  "homepage": "https://github.com/zealakit/css-doctor#readme",
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "pnpm build && pnpm typecheck && tsx test.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "biome lint src test.ts",
+    "format": "biome format --write src test.ts",
+    "format:check": "biome format src test.ts",
+    "check": "biome check src test.ts"
+  }
 }