From f1910d13172011decb08b4ca97ae4614bbb90bcf Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Tue, 23 Dec 2025 19:32:46 -0600
Subject: [PATCH] docs: odd prime numbers rule.

---
 README.md                        | 243 +++-------------------------
 package-lock.json                | 269 +------------------------------
 packages/css/README.md           | 247 ++++++++++++++++++++++++++++
 packages/css/package.json        |   5 +-
 packages/playwright/package.json |   2 +-
 5 files changed, 277 insertions(+), 489 deletions(-)
 create mode 100644 packages/css/README.md

diff --git a/README.md b/README.md
index 02a28e9..3f51f87 100644
--- a/README.md
+++ b/README.md
@@ -1,246 +1,53 @@
-# [`@knighted/css`](https://github.com/knightedcodemonkey/css)
+# [`@knighted/css`](https://www.npmjs.com/package/@knighted/css)
 
 ![CI](https://github.com/knightedcodemonkey/css/actions/workflows/ci.yml/badge.svg)
 [![codecov](https://codecov.io/gh/knightedcodemonkey/css/graph/badge.svg?token=q93Qqwvq6l)](https://codecov.io/gh/knightedcodemonkey/css)
 [![NPM version](https://img.shields.io/npm/v/@knighted/css.svg)](https://www.npmjs.com/package/@knighted/css)
 
-`@knighted/css` walks your JavaScript/TypeScript module graph, compiles every CSS-like dependency (plain CSS, Sass/SCSS, Less, vanilla-extract), and ships both the concatenated stylesheet string and optional `.knighted-css.*` imports that keep selectors typed. Use it when you need fully materialized styles ahead of runtime—Shadow DOM surfaces, server-rendered routes, static site builds, or any entry point that should inline CSS without spinning up a full bundler.
+`@knighted/css` is a zero-bundler CSS pipeline for JavaScript and TypeScript projects. Point it at an entry module and it walks the graph, compiles every CSS-like dependency (CSS, Sass/SCSS, Less, vanilla-extract), and hands back both a concatenated stylesheet string and optional `.knighted-css.*` selector manifests for type-safe loaders.
 
-## Why
+## What it does (at a glance)
 
-I needed a single source of truth for UI components that could drop into both light DOM pages and Shadow DOM hosts, without losing encapsulated styling in the latter.
+- **Graph walking**: Follows `import` trees the same way Node does (tsconfig `paths`, package `exports`/`imports`, hash specifiers, etc.) using [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver).
+- **Multi-dialect compilation**: Runs Sass, Less, Lightning CSS, or vanilla-extract integrations on demand so every dependency ends up as plain CSS.
+- **Loader + CLI**: Ship CSS at runtime via `?knighted-css` loader queries or ahead of time via the `css()` API and the `knighted-css-generate-types` command.
+- **Shadow DOM + SSR ready**: Inline styles in server renders, ship them alongside web components, or keep classic DOM apps in sync—all without wiring a full bundler.
 
-## Quick Links
+See the [docs/](./docs) directory for deep dives on loaders, type generation, specificity boosts, Sass aliases, and the combined import queries.
 
-- [Features](#features)
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [API](#api)
-- [Entry points (`import`)](#entry-points-at-a-glance)
-- [Examples](#examples)
-- [Demo](#demo)
+## Workspaces in this repo
 
-## Features
+| Workspace             | NPM Name                                                       | What it contains                                                                                                                                                                          |
+| --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `packages/css`        | [`@knighted/css`](https://www.npmjs.com/package/@knighted/css) | The production library: graph walker, compilation pipeline, loader helpers, CLI, and docs. Published to npm and meant for real builds.                                                    |
+| `packages/playwright` | `@knighted/css-playwright-fixture`                             | The end-to-end demo + regression suite. Playwright drives Lit + React examples, hash-import workspace scenarios, and SSR checks to ensure the core package keeps working across bundlers. |
 
-- Traverses module graphs with a built-in walker to find transitive style imports (no bundler required).
-- Resolution parity via [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver): tsconfig `paths`, package `exports` + `imports`, and extension aliasing (e.g., `.css.js` → `.css.ts`) are honored without wiring up a bundler.
-- Compiles `*.css`, `*.scss`, `*.sass`, `*.less`, and `*.css.ts` (vanilla-extract) files out of the box.
-- Optional post-processing via [`lightningcss`](https://github.com/parcel-bundler/lightningcss) for minification, prefixing, media query optimizations, or specificity boosts.
-- Pluggable resolver/filter hooks for custom module resolution (e.g., Rspack/Vite/webpack aliases) or selective inclusion.
-- First-class loader (`@knighted/css/loader`) so bundlers can import compiled CSS alongside their modules via `?knighted-css`.
-- Built-in type generation CLI (`knighted-css-generate-types`) that emits `.knighted-css.*` selector manifests so TypeScript gets literal tokens in lockstep with the loader exports.
+Each workspace is a standalone npm project. Run commands from the repo root with `npm run <script> -w <workspace>` or `npm run <script> --workspaces` to fan out when needed.
 
-## Requirements
-
-- Node.js `>= 22.17.0`
-- npm `>= 10.9.0`
-- Install peer toolchains you intend to use (`sass`, `less`, `@vanilla-extract/integration`, etc.).
-
-## Installation
-
-```bash
-npm install @knighted/css
-```
-
-Install the peers your project is using, for example `less`, or `sass`, etc.
-
-## Quick Start
+## Quick start
 
 ```ts
-// scripts/extract-styles.ts
 import { css } from '@knighted/css'
 
-const styles = await css('./src/components/app.ts', {
+const sheet = await css('./src/entry.tsx', {
   cwd: process.cwd(),
   lightningcss: { minify: true },
 })
 
-console.log(styles)
-```
-
-Run it with `tsx`/`node` and you will see a fully inlined stylesheet for `app.ts` and every style import it references, regardless of depth.
-
-## API
-
-```ts
-type CssOptions = {
-  extensions?: string[] // customize file extensions to scan
-  cwd?: string // working directory (defaults to process.cwd())
-  filter?: (filePath: string) => boolean
-  lightningcss?: boolean | LightningTransformOptions
-  specificityBoost?: {
-    visitor?: LightningTransformOptions<never>['visitor']
-    strategy?: SpecificityStrategy
-    match?: SpecificitySelector[]
-  }
-  moduleGraph?: ModuleGraphOptions
-  resolver?: (
-    specifier: string,
-    ctx: { cwd: string; from?: string },
-  ) => string | Promise<string | undefined>
-  peerResolver?: (name: string) => Promise<unknown> // for custom module loading
-}
-
-async function css(entry: string, options?: CssOptions): Promise<string>
-```
-
-## Entry points at a glance
-
-### Runtime loader hook (`?knighted-css`)
-
-Import any module with the `?knighted-css` query to receive the compiled stylesheet string:
-
-```ts
-import { knightedCss } from './button.js?knighted-css'
-```
-
-See [docs/loader.md](./docs/loader.md) for the full configuration, combined imports, and `&types` runtime selector map guidance.
-
-### Type generation hook (`*.knighted-css*`)
-
-Run `knighted-css-generate-types` so every specifier that ends with `.knighted-css` produces a sibling manifest containing literal selector tokens:
-
-```ts
-import stableSelectors from './button.module.scss.knighted-css.js'
-```
-
-Refer to [docs/type-generation.md](./docs/type-generation.md) for CLI options and workflow tips.
-
-### Combined + runtime selectors
-
-Need the module exports, `knightedCss`, and a runtime `stableSelectors` map from one import? Use `?knighted-css&combined&types` (plus optional `&named-only`). Example:
-
-```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
-import type { ButtonStableSelectors } from './button.css.knighted-css.js'
-import * as buttonModule from './button.js?knighted-css&combined&types'
-
-const {
-  default: Button,
-  knightedCss,
-  stableSelectors,
-} = asKnightedCssCombinedModule<
-  typeof import('./button.js'),
-  { stableSelectors: Readonly<Record<keyof ButtonStableSelectors, string>> }
->(buttonModule)
-
-stableSelectors.shell
-```
-
-> [!NOTE]
-> `stableSelectors` here is for runtime use; TypeScript still reads literal tokens from the generated `.knighted-css.*` modules. For a full decision matrix, see [docs/combined-queries.md](./docs/combined-queries.md).
-> Prefer importing `asKnightedCssCombinedModule` from `@knighted/css/loader-helpers` instead of grabbing it from `@knighted/css/loader`—the helper lives in a Node-free chunk so both browser and server bundles stay happy.
-
-## Examples
-
-- [Generate standalone stylesheets](#generate-standalone-stylesheets)
-- [Inline CSS during SSR](#inline-css-during-ssr)
-- [Custom resolver](#custom-resolver-enhanced-resolve-example)
-- [Specificity boost](#specificity-boost)
-- [Bundler loader](./docs/loader.md#loader-example)
-
-### Generate standalone stylesheets
-
-```ts
-import { writeFile } from 'node:fs/promises'
-import { css } from '@knighted/css'
-
-// Build-time script that gathers all CSS imported by a React route
-const sheet = await css('./src/routes/marketing-page.tsx', {
-  lightningcss: { minify: true, targets: { chrome: 120, safari: 17 } },
-})
-
-await writeFile('./dist/marketing-page.css', sheet)
-```
-
-### Inline CSS during SSR
-
-```ts
-import { renderToString } from 'react-dom/server'
-import { css } from '@knighted/css'
-
-export async function render(url: string) {
-  const styles = await css('./src/routes/root.tsx')
-  const html = renderToString(<App url={url} />)
-  return `<!doctype html><style>${styles}</style>${html}`
-}
-```
-
-### Custom resolver (enhanced-resolve example)
-
-The built-in walker already leans on [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver), so tsconfig `paths`, package `exports` conditions, and common extension aliases work out of the box. If you still need to mirror bespoke behavior (virtual modules, framework-specific loaders, etc.), plug in a custom resolver. Here’s how to use [`enhanced-resolve`](https://github.com/webpack/enhanced-resolve):
-
-> [!TIP]
-> Hash-prefixed specifiers defined in `package.json#imports` resolve automatically—no extra loader or `css()` options required. Reach for a custom resolver only when you need behavior beyond what `oxc-resolver` already mirrors.
-
-> [!NOTE]
-> Sass-specific prefixes such as `pkg:#button` live outside Node’s resolver and still need a shim. See [docs/sass-import-aliases.md](./docs/sass-import-aliases.md) for a drop-in helper that strips those markers before `@knighted/css` walks the graph.
-
-```ts
-import { ResolverFactory } from 'enhanced-resolve'
-import { css } from '@knighted/css'
-
-const resolver = ResolverFactory.createResolver({
-  extensions: ['.ts', '.tsx', '.js'],
-  mainFiles: ['index'],
-})
-
-async function resolveWithEnhanced(id: string, cwd: string): Promise<string | undefined> {
-  return new Promise((resolve, reject) => {
-    resolver.resolve({}, cwd, id, {}, (err, result) => {
-      if (err) return reject(err)
-      resolve(result ?? undefined)
-    })
-  })
-}
-
-const styles = await css('./src/routes/page.tsx', {
-  resolver: (specifier, { cwd }) => resolveWithEnhanced(specifier, cwd),
-})
-```
-
-This keeps `@knighted/css` resolution in sync with your bundler’s alias/extension rules.
-
-### Specificity boost
-
-Use `specificityBoost` to tweak selector behavior:
-
-- **Strategies (built-in)**:
-  - `repeat-class` duplicates the last class in matching selectors to raise specificity (useful when you need a real specificity bump).
-  - `append-where` appends `:where(.token)` (zero specificity) for a harmless, order-based tie-breaker without changing matching.
-- **Custom visitor**: Supply your own Lightning CSS visitor via `specificityBoost.visitor` for full control.
-- **match filtering**: Provide `match: (string | RegExp)[]` to target selectors. Matches are OR’d; if any entry matches, the strategy applies. If omitted/empty, all selectors are eligible.
-
-Example:
-
-```ts
-import { css } from '@knighted/css'
-
-const styles = await css('./src/entry.ts', {
-  lightningcss: { minify: true },
-  specificityBoost: {
-    match: ['.card', /^\.btn/], // OR match
-    strategy: { type: 'repeat-class', times: 1 },
-  },
-})
+console.log(sheet) // use during SSR, static builds, or to inline Shadow DOM styles
 ```
 
-If you omit `match`, the strategy applies to all selectors. Use `append-where` when you don’t want to change specificity; use `repeat-class` when you do.
-
-> [!NOTE]
-> For the built-in strategies, the last class in a matching selector is the one that gets duplicated/appended. If you have multiple similar classes, tighten your `match` (string or RegExp) to target exactly the selector you want boosted.
-
-> [!TIP]
-> See [docs/specificity-boost-visitor.md](./docs/specificity-boost-visitor.md) for a concrete visitor example.
+- Need runtime imports? See [docs/loader.md](./docs/loader.md).
+- Want strong selector types? Run `npx knighted-css-generate-types` and follow [docs/type-generation.md](./docs/type-generation.md).
+- Hash-prefixed or Sass-specific specifiers? Guidance lives in [docs/hash-import-fixture.md](./docs/hash-import-fixture.md) and [docs/sass-import-aliases.md](./docs/sass-import-aliases.md).
 
-## Demo
+## Contributing & Support
 
-Want to see everything wired together? Check the full demo app at [css-jsx-app](https://github.com/morganney/css-jsx-app).
+1. Install deps with `npm install`.
+2. Run `npm run build` to compile `@knighted/css`.
+3. Use `npm run test` for unit coverage and `npm run test:e2e` for the Playwright matrix.
 
-> [!TIP]
-> This repo also includes a [playwright workspace](./packages/playwright/src/lit-react/lit-host.ts) which serves as an end-to-end demo.
+Issues and feature ideas are always welcome via [GitHub issues](https://github.com/knightedcodemonkey/css/issues).
 
 ## License
 
diff --git a/package-lock.json b/package-lock.json
index aa93fe8..106a37c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11922,7 +11922,7 @@
     },
     "packages/css": {
       "name": "@knighted/css",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "license": "MIT",
       "dependencies": {
         "es-module-lexer": "^2.0.0",
@@ -12222,7 +12222,7 @@
       "name": "@knighted/css-playwright-fixture",
       "version": "0.0.0",
       "dependencies": {
-        "@knighted/css": "1.0.2",
+        "@knighted/css": "1.0.3",
         "@knighted/jsx": "^1.4.1",
         "lit": "^3.2.1",
         "react": "^19.0.0",
@@ -12236,271 +12236,6 @@
         "webpack": "^5.97.1",
         "webpack-cli": "^5.1.4"
       }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-android-arm64": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm64/-/binding-android-arm64-0.104.0.tgz",
-      "integrity": "sha512-2a4tk6mtkPbGwT4Zi8pjOqMkmkrvc/Pussmas+uXoiCVv7sn7P7Jn93ATu/HK49dxIwvrvQCZ3BcS0KhAvKxlQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-darwin-arm64": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-arm64/-/binding-darwin-arm64-0.104.0.tgz",
-      "integrity": "sha512-qprm6/Hr35TSCkJoo+huRHq3siyqRyMBtNVNJQkJorZAGcffQTzzdhmzJnA7TQc+WnN36/Jq56D7/INu0/2knQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-darwin-x64": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-x64/-/binding-darwin-x64-0.104.0.tgz",
-      "integrity": "sha512-Xpu0l/l2zCUeheIrpu7dz6FxQ96W0f8Dq9rhYE1yLtTqQpMGhefnEV5Lr8qd15clwniZiKWZO6FGQawQ7npt3Q==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-freebsd-x64": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-freebsd-x64/-/binding-freebsd-x64-0.104.0.tgz",
-      "integrity": "sha512-I++fE3ZrhjtLzA0mqFcC/GuA6+dWNa/QkJJfm7sS4NGGQhipQQ2vikCK6jZK1YGIsbDFDrSoQCfA3tQfeK6pqg==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-arm-gnueabihf": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.104.0.tgz",
-      "integrity": "sha512-JkvwCNZm3ZwVG1r+c3LrcrxpJ1YXAtYEbVwOcwe+wh6LnltGoxEEZk7Zo9259jch8GiWW6AfRGDQY2FxzWJT7A==",
-      "cpu": [
-        "arm"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-arm64-gnu": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.104.0.tgz",
-      "integrity": "sha512-CD9Tzp3dfMtujHikS0JwTIOaDUCBWItvziUTDYsMXrfVHjfSaGGsaKqIQmNsG1Qg7QdmtMZtMW0pQcHGZQ2OoA==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-arm64-musl": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.104.0.tgz",
-      "integrity": "sha512-lARUu7lrZ7CoAm2arLJQkq9Sem2NiC3DaphmPvlf2X+ngkWcYUCRxZanhe+++x/bVzKrwvxormC3IVaulP51mQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-riscv64-gnu": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.104.0.tgz",
-      "integrity": "sha512-hnPWrncj89/7AiMt19Juqpa04z8OpJrIf3/ToGkJafZ3A1ZN50atyNKQD5EmGs2/gdaFxF4hG3zUnLKhX9nTtQ==",
-      "cpu": [
-        "riscv64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-s390x-gnu": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.104.0.tgz",
-      "integrity": "sha512-VegcKzBgUoHQ/p5NyV+GrdEgJEXhX4AD+kCZng+viP/eNsZJgmp2K1jDBCeLSUZIdSmdldK5wlSma3Bf8MKcUQ==",
-      "cpu": [
-        "s390x"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-x64-gnu": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.104.0.tgz",
-      "integrity": "sha512-nDtCJIwaNgVNLR1EOgb1Xsz7VL3TOASLRbQEC+wLZycs3CCETlGNQht5OqwXPNjbem61kl4l8dvuEavu8BRT/Q==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-linux-x64-musl": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-musl/-/binding-linux-x64-musl-0.104.0.tgz",
-      "integrity": "sha512-E98MNPE3d88D2xUABQYWH2cYqLA/mmOM4XL3CZHaG5dM68sN3fzCyV0ryK5skq4hVK1L2e6jk79z5oLArsCYyA==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-wasm32-wasi": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-wasm32-wasi/-/binding-wasm32-wasi-0.104.0.tgz",
-      "integrity": "sha512-I+xnHDxkInzHBZV+YERIvvrt+GFwEBdgq/RUax5jLl8yHg5iPVq11qtGh3m+2v8zAjQXYPmBbcANNGWwgXqtWQ==",
-      "cpu": [
-        "wasm32"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "@napi-rs/wasm-runtime": "^1.1.0"
-      },
-      "engines": {
-        "node": ">=14.0.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-win32-arm64-msvc": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.104.0.tgz",
-      "integrity": "sha512-EWHVWfllZGTJFWfjfBKzvS/0uuw6/Z3+o598VTvySamy5fz2f4P1mNElvTi4tGGhbm1sGTYnYRNRW8XBAnGUGg==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-parser/binding-win32-x64-msvc": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.104.0.tgz",
-      "integrity": "sha512-Nj7zeywIvxBRRd0I6NrdGufOOdiwQcAKnkRwtWo5dejPTmR1XM+9iRHJztoKacejW5+VOdEwQrfCjpa8MdLJBQ==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "packages/playwright/node_modules/@oxc-project/types": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.104.0.tgz",
-      "integrity": "sha512-We30k+29WpOerl3gCb1v8IFL4vmKTkghjist4TQ89yw7adGDCKFGf8+4mA4H3Ek5ajRzzBZ7BtGY8aIaOv9oFQ==",
-      "license": "MIT",
-      "funding": {
-        "url": "https://github.com/sponsors/Boshen"
-      }
-    },
-    "packages/playwright/node_modules/oxc-parser": {
-      "version": "0.104.0",
-      "resolved": "https://registry.npmjs.org/oxc-parser/-/oxc-parser-0.104.0.tgz",
-      "integrity": "sha512-sIEpobLwe7KhW1JdTvBJkNDgjJarHNsx+Q37iRNyASvmlDOD+f8Qirvwp6nFNz7Q5q3JcsJ1dpKM+oMPTDF/dw==",
-      "license": "MIT",
-      "dependencies": {
-        "@oxc-project/types": "^0.104.0"
-      },
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/Boshen"
-      },
-      "optionalDependencies": {
-        "@oxc-parser/binding-android-arm64": "0.104.0",
-        "@oxc-parser/binding-darwin-arm64": "0.104.0",
-        "@oxc-parser/binding-darwin-x64": "0.104.0",
-        "@oxc-parser/binding-freebsd-x64": "0.104.0",
-        "@oxc-parser/binding-linux-arm-gnueabihf": "0.104.0",
-        "@oxc-parser/binding-linux-arm64-gnu": "0.104.0",
-        "@oxc-parser/binding-linux-arm64-musl": "0.104.0",
-        "@oxc-parser/binding-linux-riscv64-gnu": "0.104.0",
-        "@oxc-parser/binding-linux-s390x-gnu": "0.104.0",
-        "@oxc-parser/binding-linux-x64-gnu": "0.104.0",
-        "@oxc-parser/binding-linux-x64-musl": "0.104.0",
-        "@oxc-parser/binding-openharmony-arm64": "0.104.0",
-        "@oxc-parser/binding-wasm32-wasi": "0.104.0",
-        "@oxc-parser/binding-win32-arm64-msvc": "0.104.0",
-        "@oxc-parser/binding-win32-x64-msvc": "0.104.0"
-      }
     }
   }
 }
diff --git a/packages/css/README.md b/packages/css/README.md
new file mode 100644
index 0000000..b35e617
--- /dev/null
+++ b/packages/css/README.md
@@ -0,0 +1,247 @@
+# [`@knighted/css`](../../README.md)
+
+![CI](https://github.com/knightedcodemonkey/css/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/knightedcodemonkey/css/graph/badge.svg?token=q93Qqwvq6l)](https://codecov.io/gh/knightedcodemonkey/css)
+[![NPM version](https://img.shields.io/npm/v/@knighted/css.svg)](https://www.npmjs.com/package/@knighted/css)
+
+`@knighted/css` walks your JavaScript/TypeScript module graph, compiles every CSS-like dependency (plain CSS, Sass/SCSS, Less, vanilla-extract), and ships both the concatenated stylesheet string and optional `.knighted-css.*` imports that keep selectors typed. Use it when you need fully materialized styles ahead of runtime—Shadow DOM surfaces, server-rendered routes, static site builds, or any entry point that should inline CSS without spinning up a full bundler.
+
+## Why
+
+I needed a single source of truth for UI components that could drop into both light DOM pages and Shadow DOM hosts, without losing encapsulated styling in the latter.
+
+## Quick Links
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API](#api)
+- [Entry points (`import`)](#entry-points-at-a-glance)
+- [Examples](#examples)
+- [Demo](#demo)
+
+## Features
+
+- Traverses module graphs with a built-in walker to find transitive style imports (no bundler required).
+- Resolution parity via [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver): tsconfig `paths`, package `exports` + `imports`, and extension aliasing (e.g., `.css.js` → `.css.ts`) are honored without wiring up a bundler.
+- Compiles `*.css`, `*.scss`, `*.sass`, `*.less`, and `*.css.ts` (vanilla-extract) files out of the box.
+- Optional post-processing via [`lightningcss`](https://github.com/parcel-bundler/lightningcss) for minification, prefixing, media query optimizations, or specificity boosts.
+- Pluggable resolver/filter hooks for custom module resolution (e.g., Rspack/Vite/webpack aliases) or selective inclusion.
+- First-class loader (`@knighted/css/loader`) so bundlers can import compiled CSS alongside their modules via `?knighted-css`.
+- Built-in type generation CLI (`knighted-css-generate-types`) that emits `.knighted-css.*` selector manifests so TypeScript gets literal tokens in lockstep with the loader exports.
+
+## Requirements
+
+- Node.js `>= 22.17.0`
+- npm `>= 10.9.0`
+- Install peer toolchains you intend to use (`sass`, `less`, `@vanilla-extract/integration`, etc.).
+
+## Installation
+
+```bash
+npm install @knighted/css
+```
+
+Install the peers your project is using, for example `less`, or `sass`, etc.
+
+## Quick Start
+
+```ts
+// scripts/extract-styles.ts
+import { css } from '@knighted/css'
+
+const styles = await css('./src/components/app.ts', {
+  cwd: process.cwd(),
+  lightningcss: { minify: true },
+})
+
+console.log(styles)
+```
+
+Run it with `tsx`/`node` and you will see a fully inlined stylesheet for `app.ts` and every style import it references, regardless of depth.
+
+## API
+
+```ts
+type CssOptions = {
+  extensions?: string[] // customize file extensions to scan
+  cwd?: string // working directory (defaults to process.cwd())
+  filter?: (filePath: string) => boolean
+  lightningcss?: boolean | LightningTransformOptions
+  specificityBoost?: {
+    visitor?: LightningTransformOptions<never>['visitor']
+    strategy?: SpecificityStrategy
+    match?: SpecificitySelector[]
+  }
+  moduleGraph?: ModuleGraphOptions
+  resolver?: (
+    specifier: string,
+    ctx: { cwd: string; from?: string },
+  ) => string | Promise<string | undefined>
+  peerResolver?: (name: string) => Promise<unknown> // for custom module loading
+}
+
+async function css(entry: string, options?: CssOptions): Promise<string>
+```
+
+## Entry points at a glance
+
+### Runtime loader hook (`?knighted-css`)
+
+Import any module with the `?knighted-css` query to receive the compiled stylesheet string:
+
+```ts
+import { knightedCss } from './button.js?knighted-css'
+```
+
+See [docs/loader.md](../../docs/loader.md) for the full configuration, combined imports, and `&types` runtime selector map guidance.
+
+### Type generation hook (`*.knighted-css*`)
+
+Run `knighted-css-generate-types` so every specifier that ends with `.knighted-css` produces a sibling manifest containing literal selector tokens:
+
+```ts
+import stableSelectors from './button.module.scss.knighted-css.js'
+```
+
+Refer to [docs/type-generation.md](../../docs/type-generation.md) for CLI options and workflow tips.
+
+### Combined + runtime selectors
+
+Need the module exports, `knightedCss`, and a runtime `stableSelectors` map from one import? Use `?knighted-css&combined&types` (plus optional `&named-only`). Example:
+
+```ts
+import type { KnightedCssCombinedModule } from '@knighted/css/loader'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import type { ButtonStableSelectors } from './button.css.knighted-css.js'
+import * as buttonModule from './button.js?knighted-css&combined&types'
+
+const {
+  default: Button,
+  knightedCss,
+  stableSelectors,
+} = asKnightedCssCombinedModule<
+  typeof import('./button.js'),
+  { stableSelectors: Readonly<Record<keyof ButtonStableSelectors, string>> }
+>(buttonModule)
+
+stableSelectors.shell
+```
+
+> [!NOTE]
+> `stableSelectors` here is for runtime use; TypeScript still reads literal tokens from the generated `.knighted-css.*` modules. For a full decision matrix, see [docs/combined-queries.md](../../docs/combined-queries.md).
+> Prefer importing `asKnightedCssCombinedModule` from `@knighted/css/loader-helpers` instead of grabbing it from `@knighted/css/loader`—the helper lives in a Node-free chunk so both browser and server bundles stay happy.
+
+## Examples
+
+- [Generate standalone stylesheets](#generate-standalone-stylesheets)
+- [Inline CSS during SSR](#inline-css-during-ssr)
+- [Custom resolver](#custom-resolver-enhanced-resolve-example)
+- [Specificity boost](#specificity-boost)
+- [Bundler loader](../../docs/loader.md#loader-example)
+
+### Generate standalone stylesheets
+
+```ts
+import { writeFile } from 'node:fs/promises'
+import { css } from '@knighted/css'
+
+// Build-time script that gathers all CSS imported by a React route
+const sheet = await css('./src/routes/marketing-page.tsx', {
+  lightningcss: { minify: true, targets: { chrome: 120, safari: 17 } },
+})
+
+await writeFile('./dist/marketing-page.css', sheet)
+```
+
+### Inline CSS during SSR
+
+```ts
+import { renderToString } from 'react-dom/server'
+import { css } from '@knighted/css'
+
+export async function render(url: string) {
+  const styles = await css('./src/routes/root.tsx')
+  const html = renderToString(<App url={url} />)
+  return `<!doctype html><style>${styles}</style>${html}`
+}
+```
+
+### Custom resolver (enhanced-resolve example)
+
+The built-in walker already leans on [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver), so tsconfig `paths`, package `exports` conditions, and common extension aliases work out of the box. If you still need to mirror bespoke behavior (virtual modules, framework-specific loaders, etc.), plug in a custom resolver. Here’s how to use [`enhanced-resolve`](https://github.com/webpack/enhanced-resolve):
+
+> [!TIP]
+> Hash-prefixed specifiers defined in `package.json#imports` resolve automatically—no extra loader or `css()` options required. Reach for a custom resolver only when you need behavior beyond what `oxc-resolver` already mirrors.
+
+> [!NOTE]
+> Sass-specific prefixes such as `pkg:#button` live outside Node’s resolver and still need a shim. See [docs/sass-import-aliases.md](../../docs/sass-import-aliases.md) for a drop-in helper that strips those markers before `@knighted/css` walks the graph.
+
+```ts
+import { ResolverFactory } from 'enhanced-resolve'
+import { css } from '@knighted/css'
+
+const resolver = ResolverFactory.createResolver({
+  extensions: ['.ts', '.tsx', '.js'],
+  mainFiles: ['index'],
+})
+
+async function resolveWithEnhanced(id: string, cwd: string): Promise<string | undefined> {
+  return new Promise((resolve, reject) => {
+    resolver.resolve({}, cwd, id, {}, (err, result) => {
+      if (err) return reject(err)
+      resolve(result ?? undefined)
+    })
+  })
+}
+
+const styles = await css('./src/routes/page.tsx', {
+  resolver: (specifier, { cwd }) => resolveWithEnhanced(specifier, cwd),
+})
+```
+
+This keeps `@knighted/css` resolution in sync with your bundler’s alias/extension rules.
+
+### Specificity boost
+
+Use `specificityBoost` to tweak selector behavior:
+
+- **Strategies (built-in)**:
+  - `repeat-class` duplicates the last class in matching selectors to raise specificity (useful when you need a real specificity bump).
+  - `append-where` appends `:where(.token)` (zero specificity) for a harmless, order-based tie-breaker without changing matching.
+- **Custom visitor**: Supply your own Lightning CSS visitor via `specificityBoost.visitor` for full control.
+- **match filtering**: Provide `match: (string | RegExp)[]` to target selectors. Matches are OR’d; if any entry matches, the strategy applies. If omitted/empty, all selectors are eligible.
+
+Example:
+
+```ts
+import { css } from '@knighted/css'
+
+const styles = await css('./src/entry.ts', {
+  lightningcss: { minify: true },
+  specificityBoost: {
+    match: ['.card', /^\.btn/], // OR match
+    strategy: { type: 'repeat-class', times: 1 },
+  },
+})
+```
+
+If you omit `match`, the strategy applies to all selectors. Use `append-where` when you don’t want to change specificity; use `repeat-class` when you do.
+
+> [!NOTE]
+> For the built-in strategies, the last class in a matching selector is the one that gets duplicated/appended. If you have multiple similar classes, tighten your `match` (string or RegExp) to target exactly the selector you want boosted.
+
+> [!TIP]
+> See [docs/specificity-boost-visitor.md](../../docs/specificity-boost-visitor.md) for a concrete visitor example.
+
+## Demo
+
+Want to see everything wired together? Check the full demo app at [css-jsx-app](https://github.com/morganney/css-jsx-app).
+
+> [!TIP]
+> This repo also includes a [playwright workspace](../playwright/src/lit-react/lit-host.ts) which serves as an end-to-end demo.
+
+## License
+
+MIT © Knighted Code Monkey
diff --git a/packages/css/package.json b/packages/css/package.json
index 57e63b9..0dba00c 100644
--- a/packages/css/package.json
+++ b/packages/css/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A build-time utility that traverses JavaScript/TypeScript module dependency graphs to extract, compile, and optimize all imported CSS into a single, in-memory string.",
   "type": "module",
   "main": "./dist/css.js",
@@ -114,8 +114,7 @@
     "types.d.ts",
     "stable",
     "bin",
-    "types-stub",
-    "README.md"
+    "types-stub"
   ],
   "author": "KCM <knightedcodemonkey@gmail.com>",
   "license": "MIT",
diff --git a/packages/playwright/package.json b/packages/playwright/package.json
index 5f95a70..b627161 100644
--- a/packages/playwright/package.json
+++ b/packages/playwright/package.json
@@ -15,7 +15,7 @@
     "pretest": "npm run build"
   },
   "dependencies": {
-    "@knighted/css": "1.0.2",
+    "@knighted/css": "1.0.3",
     "@knighted/jsx": "^1.4.1",
     "lit": "^3.2.1",
     "react": "^19.0.0",