@zealamic/css-doctor-binding 0.0.0-stage → 1.0.0-beta.1

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.
+# @zealamic/css-doctor-binding
+
+**Native NAPI-RS bridge for the css-doctor LightningCSS engine.**
+
+Version 1.0.0-beta.1
+
+[English](./README.md) | [Tiếng Việt](./README_VI.md) | [简体中文](./README_CN.md)
+
+</div>
+
+---
+
+## Installation
+
+```bash
+pnpm add @zealamic/css-doctor-binding
+```
+
+## Usage
+
+```ts
+import { analyzeCss, optimizeCss } from "@zealamic/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 @zealamic/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](../../README.md) | [Tiếng Việt](../../README_VI.md) | [简体中文](../../README_CN.md)

package/index.d.ts

@@ -0,0 +1,298 @@
+/* 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

package/index.js

@@ -0,0 +1,321 @@
+/* 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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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('@zealamic/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 } = 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

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@zealamic/css-doctor-binding",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-beta.1",
+  "description": "Native Node.js bindings for the css-doctor CSS analysis engine",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "*.node"
+  ],
+  "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"
+  },
+  "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"
+  }
 }