docs: plugin.

Author: knightedcodemonkey

docs/loader.md

@@ -53,6 +53,8 @@ augmented exports to be present on the original JS/TS module. Use the resolver p
 to automatically append `?knighted-css` for any module import that has a generated
 sidecar `.d.ts` file.
 
+See [docs/plugin.md](./plugin.md) for full resolver plugin documentation.
+
 ```js
 // rspack.config.js
 import { knightedCssResolverPlugin } from '@knighted/css/plugin'

docs/plugin.md

@@ -0,0 +1,143 @@
+# Resolver plugin (`knightedCssResolverPlugin`)
+
+`knightedCssResolverPlugin` is the resolver companion for declaration mode. It teaches your
+bundler to rewrite module imports to `?knighted-css` (and `&combined` when applicable) when a
+matching declaration sidecar exists, so runtime exports stay aligned with the generated types.
+
+Without the plugin, TypeScript may compile, but the bundler will load the original module
+without the loader query. That means `knightedCss`, `stableSelectors`, or other injected exports
+will be missing at runtime.
+
+## What it does
+
+- Scans resolved JS/TS module requests.
+- Looks for a declaration sidecar (`.d.ts`) generated by `knighted-css-generate-types --mode declaration`.
+- If a sidecar is found, rewrites the request to append `?knighted-css`.
+- Optionally enforces strict sidecar matches using a manifest to avoid accidental rewrites.
+- Optionally marks “combined” entries (via `combinedPaths`) so the query includes `&combined`.
+
+## Options
+
+```ts
+import { KnightedCssResolverPlugin } from '@knighted/css/plugin'
+
+new KnightedCssResolverPlugin({
+  rootDir: string,
+  tsconfig: string | Record<string, unknown>,
+  conditions: string[],
+  extensions: string[],
+  debug: boolean,
+  combinedPaths: Array<string | RegExp>,
+  strictSidecar: boolean,
+  manifestPath: string,
+})
+```
+
+- `rootDir` (optional): Base directory used for resolver scoping. Defaults to `process.cwd()`.
+- `tsconfig` (optional): Path to a tsconfig or an in-memory tsconfig object for path resolution.
+- `conditions` (optional): Custom `package.json` export conditions to honor during resolution.
+- `extensions` (optional): File extensions considered as script modules. Defaults to
+  `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`.
+- `debug` (optional): Logs rewrite decisions and a summary of cache hits/misses.
+- `combinedPaths` (optional): List of strings or regexes. Any resolved path that matches will
+  receive `&combined` alongside `?knighted-css`.
+- `strictSidecar` (optional): When true, only modules present in the manifest are rewritten.
+  Defaults to true when `manifestPath` is provided.
+- `manifestPath` (optional): Path to the sidecar manifest generated by
+  `knighted-css-generate-types --manifest`. Used for strict matching.
+
+## Basic usage (declaration mode)
+
+```js
+// rspack.config.js
+import { KnightedCssResolverPlugin } from '@knighted/css/plugin'
+
+export default {
+  resolve: {
+    plugins: [new KnightedCssResolverPlugin()],
+  },
+}
+```
+
+```ts
+// Type generation
+knighted-css-generate-types --root . --include src --mode declaration
+```
+
+This lets you write clean imports while still receiving `knightedCss` at runtime:
+
+```ts
+import Button, { knightedCss } from './button.js'
+```
+
+## Strict sidecar + manifest (recommended)
+
+Use strict sidecars to avoid rewriting modules that merely happen to have a `.d.ts` next to
+them. This ensures only declaration mode sidecars generated by the CLI trigger rewrites.
+
+```sh
+knighted-css-generate-types --root . --include src --mode declaration --manifest .knighted-css/knighted-manifest.json
+```
+
+```js
+// rspack.config.js
+import path from 'node:path'
+import { KnightedCssResolverPlugin } from '@knighted/css/plugin'
+
+export default {
+  resolve: {
+    plugins: [
+      new KnightedCssResolverPlugin({
+        strictSidecar: true,
+        manifestPath: path.resolve('.knighted-css/knighted-manifest.json'),
+      }),
+    ],
+  },
+}
+```
+
+## Combined imports
+
+If you have modules that are consumed with combined exports (`?knighted-css&combined`),
+set `combinedPaths` to ensure the resolver appends `&combined` during rewrites.
+
+Example of an import that relies on `&combined` at runtime:
+
+```ts
+import { Card, knightedCss } from './combined-card.js'
+```
+
+And how you would use `combinedPaths` to support that:
+
+```js
+import path from 'node:path'
+import { KnightedCssResolverPlugin } from '@knighted/css/plugin'
+
+export default {
+  resolve: {
+    plugins: [
+      new KnightedCssResolverPlugin({
+        combinedPaths: [
+          path.resolve('src/components/combined-card.tsx'),
+          /src\/views\/.*\.tsx$/,
+        ],
+      }),
+    ],
+  },
+}
+```
+
+## Debugging
+
+Enable `debug: true` to log each decision and a final summary that includes counts for
+rewrites, cache hits, marker misses, and manifest misses.
+
+```js
+import { KnightedCssResolverPlugin } from '@knighted/css/plugin'
+
+export default {
+  resolve: {
+    plugins: [new KnightedCssResolverPlugin({ debug: true })],
+  },
+}
+```

docs/type-generation.md

@@ -40,6 +40,7 @@ Wire it into `postinstall` or your build so new selectors land automatically.
 | `declaration`      | Plain JS/TS imports                | `.d.ts` augmentations next to modules | Required (append `?knighted-css`) | Cleaner imports when you accept resolver overhead  |
 
 If you use declaration mode, prefer enabling strict sidecars + a manifest so the resolver only rewrites imports that the CLI generated.
+See [docs/plugin.md](./plugin.md) for resolver plugin details and configuration options.
 
 ### Relationship to the loader
 
@@ -80,6 +81,7 @@ import Button, { knightedCss, stableSelectors } from './button.js'
 > [!IMPORTANT]
 > Declaration mode requires a resolver plugin to append `?knighted-css` (and `&combined` when applicable)
 > at build time so runtime exports match the generated types.
+> See [docs/plugin.md](./plugin.md) for resolver plugin configuration.
 
 ### Sidecar manifests + strict resolver mode