## Installation
```bash
npm install @master/css-scanner
```
`@master/css-scanner` is the Node.js content-scanning engine behind Master CSS static rendering. It scans supplied source text, validates possible classes, inserts generated rules, and maintains scanner state for build integrations. Source discovery, file watching, and CSS file output are owned by CLI/framework/build integrations.
## Usage
```js
import { CSSScanner } from '@master/css-scanner'
const scanner = new CSSScanner(options, cwd)
```
`cwd` resolves project-relative module excludes and log output.
## Options
Default options are exported from the root package and the side-effect-free `./options` subpath:
```js
import { scannerOptions } from '@master/css-scanner'
import defaultScannerOptions from '@master/css-scanner/options'
```
| Option | Type | Description |
| --- | --- | --- |
| `manifest` | `MasterCSSManifest` | Explicit compiled manifest. When omitted, integrations and CLI flows load the project CSS entry manifest from `cwd`. |
| `exclude` | `string[]` | Module paths to exclude from integration-fed module scans. |
| `safelist` | `string[]` | Classes generated regardless of source detection. |
| `blocklist` | `(string \| RegExp)[]` | Classes excluded from accidental scanner matches. |
Use `safelist` for classes from asynchronous data, irregular classes, or classes that are not visible in source. Use `blocklist` for false positives.
## CSS directives
Scanner options can also be declared in CSS. For the full stylesheet syntax, see [CSS directives](https://rc.css.master.co/reference/directives).
```css
@source 'src/**/*.{html,js,jsx,ts,tsx,vue,svelte,astro,md,mdx}';
@source not 'src/**/*.test.tsx';
@safelist 'dialog-open bg:blue-60@dark';
@blocklist 'debug-*';
```
Stylesheet `@source` directives are resolved by the stylesheet pipeline as `(source union) - (source not union)`. `@safelist` maps to `safelist`, and `@blocklist` maps to `blocklist`.
Bare source globs are resolved from `cwd`. Globs that start with `./` or `../` are resolved relative to the CSS file that declares the directive. `@blocklist` accepts exact strings and `*` / `?` wildcard patterns.
## Native CSS pruning
Prune native CSS class selector rules from a stylesheet by importing `@master/css` in that stylesheet:
```css
@import "@master/css";
@import "./styles/btn.css";
.card {
color: red;
}
.unused {
color: blue;
}
```
Local relative `.css` imports are expanded, the Master import is replaced by generated CSS, and native class rules are kept only when their class names are found by the scanner. Add `@preserve native;` to preserve native CSS in a Master-managed root. See [Native CSS pruning](https://rc.css.master.co/guide/native-css-pruning) for the full model.
## Class candidate extraction
Use `@master/css-source` when a tool only needs unvalidated class-like candidates from source content:
```ts
import { extractClassCandidates } from '@master/css-source'
const result = extractClassCandidates(source)
```
