From 0b0e07181478f1e0f3706fe301fe1b681b65c3ed Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 10:03:53 -0600
Subject: [PATCH 1/7] docs: update.

---
 README.md                |  10 +--
 docs/combined-queries.md | 146 +++++++++++++++++++++++++--------------
 docs/resolution.md       |  57 +++++++++++++++
 packages/css/README.md   |   3 +-
 4 files changed, 159 insertions(+), 57 deletions(-)
 create mode 100644 docs/resolution.md

diff --git a/README.md b/README.md
index 3f51f87..1cd5392 100644
--- a/README.md
+++ b/README.md
@@ -17,10 +17,10 @@ See the [docs/](./docs) directory for deep dives on loaders, type generation, sp
 
 ## Workspaces in this repo
 
-| 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. |
+| Workspace             | NPM Name                                                              | What it contains                                                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `packages/css`        | [`@knighted/css`](./packages/css/README.md)                           | 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`](./packages/playwright/README.md) | 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. |
 
 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.
 
@@ -39,7 +39,7 @@ console.log(sheet) // use during SSR, static builds, or to inline Shadow DOM sty
 
 - 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).
+- Need the rundown on Node `exports`/`imports`, Sass prefixes, or custom resolver hooks? Start with [docs/resolution.md](./docs/resolution.md).
 
 ## Contributing & Support
 
diff --git a/docs/combined-queries.md b/docs/combined-queries.md
index 50d9126..a40e0c6 100644
--- a/docs/combined-queries.md
+++ b/docs/combined-queries.md
@@ -3,34 +3,41 @@
 This document summarizes how `?knighted-css&combined` behaves for different module export shapes and how to structure your imports accordingly. Use it as guidance when filing documentation feedback for `@knighted/css`.
 
 > [!NOTE]
-> TypeScript now reads literal selector tokens from the generated `.knighted-css.ts` modules (emitted by `knighted-css-generate-types`). Append `&types` to combined imports only when you also need `stableSelectors` at runtime—the loader still exports the map, while the double-extension modules keep your editors in sync.
-
-> [!TIP]
-> `KnightedCssCombinedModule` accepts an optional second generic parameter so you can describe loader-injected exports (for example, `{ stableSelectors: Record<string, string> }` when you append `&types`). That keeps the helper self-contained without intersecting additional types in your own code.
+> TypeScript reads literal selector tokens from the generated `.knighted-css.ts` modules (emitted by `knighted-css-generate-types`). Append `&types` to combined imports only when you also need `stableSelectors` at runtime—the loader still exports the map, while the double-extension modules keep your editors in sync.
 
 > [!TIP]
 > Prefer importing `asKnightedCssCombinedModule` from `@knighted/css/loader-helpers` when you want a runtime helper—the file has zero Node dependencies, so both browser and Node builds stay green.
 
 ## Decision Matrix
 
-| Source module exports                          | Recommended query                                                                  | TypeScript import pattern                                   | Notes                                                                                                                      |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| **Named exports only**                         | `?knighted-css&combined&named-only`                                                | [Snippet](#named-exports-only)                              | `&named-only` disables the synthetic default export so you only destructure the original named members plus `knightedCss`. |
-| **Default export only**                        | `?knighted-css&combined`                                                           | [Snippet](#default-export-only)                             | Loader mirrors the default export and adds `knightedCss`, so default-import code keeps working.                            |
-| **Default + named exports**                    | `?knighted-css&combined` (append `&named-only` when you never consume the default) | [Snippet](#default-and-named-exports)                       | Without the flag you get both default + named exports; adding it drops the synthetic default for stricter codebases.       |
-| **Named exports + stable selector map**        | `?knighted-css&combined&named-only&types`                                          | [Snippet](#named-exports-with-stable-selectors)             | Adds a `stableSelectors` named export; configure namespaces via the loader option or CLI flag.                             |
-| **Default export only + stable selector map**  | `?knighted-css&combined&types`                                                     | [Snippet](#default-export-with-stable-selectors)            | Keep your default-import flow and add `stableSelectors`; namespaces come from loader/CLI configuration.                    |
-| **Default + named exports + stable selectors** | `?knighted-css&combined&types` (append `&named-only` if you skip the default)      | [Snippet](#default-and-named-exports-with-stable-selectors) | Best of both worlds—`stableSelectors` is exported alongside `knightedCss`; add `&named-only` if you don’t use the default. |
+| Module exports                         | Recommended query                                                                  | Import pattern                                              | Notes                                                                                                                      |
+| -------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| **Named only**                         | `?knighted-css&combined&named-only`                                                | [Snippet](#named-exports-only)                              | `&named-only` disables the synthetic default export so you only destructure the original named members plus `knightedCss`. |
+| **Default only**                       | `?knighted-css&combined`                                                           | [Snippet](#default-export-only)                             | Loader mirrors the default export and adds `knightedCss`, so default-import code keeps working.                            |
+| **Default + named**                    | `?knighted-css&combined` (append `&named-only` when you never consume the default) | [Snippet](#default-and-named-exports)                       | Without the flag you get both default + named exports; adding it drops the synthetic default for stricter codebases.       |
+| **Named + stable selectors**           | `?knighted-css&combined&named-only&types`                                          | [Snippet](#named-exports-with-stable-selectors)             | Adds a `stableSelectors` named export; configure namespaces via the loader option or CLI flag.                             |
+| **Default only + stable selectors**    | `?knighted-css&combined&types`                                                     | [Snippet](#default-export-with-stable-selectors)            | Keep your default-import flow and add `stableSelectors`; namespaces come from loader/CLI configuration.                    |
+| **Default + named + stable selectors** | `?knighted-css&combined&types` (append `&named-only` if you skip the default)      | [Snippet](#default-and-named-exports-with-stable-selectors) | Best of both worlds—`stableSelectors` is exported alongside `knightedCss`; add `&named-only` if you don’t use the default. |
+
+### Jump to a scenario
+
+- [Named exports only](#named-exports-only) – drop the synthetic default and keep namespace imports tidy.
+- [Default export only](#default-export-only) – keep your default-import flow with `knightedCss` alongside.
+- [Default and named exports](#default-and-named-exports) – destructure everything without extra loader flags.
+- [Named exports with stable selectors](#named-exports-with-stable-selectors) – add `stableSelectors` while staying default-free.
+- [Default export with stable selectors](#default-export-with-stable-selectors) – default import plus runtime selector map.
+- [Default and named exports with stable selectors](#default-and-named-exports-with-stable-selectors) – grab every export plus `stableSelectors`.
 
 ## Named exports only
 
+_Use when your module only exposes named exports and you never rely on a synthetic default._
+
 ```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined from './module.js?knighted-css&combined&named-only'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import * as combinedModule from './module.js?knighted-css&combined&named-only'
 
-const { Component, knightedCss } = combined as KnightedCssCombinedModule<
-  typeof import('./module.js')
->
+const { Component, knightedCss } =
+  asKnightedCssCombinedModule<typeof import('./module.js')>(combinedModule)
 ```
 
 > [!NOTE]
@@ -38,84 +45,123 @@ const { Component, knightedCss } = combined as KnightedCssCombinedModule<
 
 ## Default export only
 
+_Use when your component only exposes a default export and you want `knightedCss` beside it._
+
 ```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined from './module.js?knighted-css&combined'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import * as combinedModule from './module.js?knighted-css&combined'
 
-const { default: Component, knightedCss } = combined as KnightedCssCombinedModule<
-  typeof import('./module.js'),
-  { stableSelectors: typeof stableSelectors }
->
+const { default: Component, knightedCss } =
+  asKnightedCssCombinedModule<typeof import('./module.js')>(combinedModule)
 ```
 
 ## Default and named exports
 
+_Use when you consume both the default export and its named helpers from the same module._
+
 ```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined from './module.js?knighted-css&combined'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import * as combinedModule from './module.js?knighted-css&combined'
 
 const {
   default: Component,
   helper,
   knightedCss,
-} = combined as KnightedCssCombinedModule<
-  typeof import('./module.js'),
-  { stableSelectors: typeof stableSelectors }
->
+} = asKnightedCssCombinedModule<typeof import('./module.js')>(combinedModule)
 ```
 
 Prefer `?knighted-css&combined&named-only` plus the [named exports only](#named-exports-only) snippet when you intentionally avoid default exports but still need the named members and `knightedCss`.
 
-## Named exports with stable selectors
+## Adding stable selectors (`&types`)
+
+Append `&types` whenever you need the runtime `stableSelectors` map in addition to `knightedCss`. Configure the loader’s `stableNamespace` option (or pass `--stable-namespace` to the CLI) so runtime exports and generated `.knighted-css.ts` modules stay aligned.
+
+### Named exports with stable selectors
+
+_Use when you only consume named exports (no default) but still want typed `stableSelectors`._
 
 ```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined, {
-  stableSelectors,
-} from './module.js?knighted-css&combined&named-only&types'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import type { KnightedCssStableSelectors as ModuleStableSelectors } from './module.css.knighted-css.js'
+import * as combinedModule from './module.js?knighted-css&combined&named-only&types'
 
-const { Component, knightedCss } = combined as KnightedCssCombinedModule<
-  typeof import('./module.js')
->
+const { Component, knightedCss, stableSelectors } = asKnightedCssCombinedModule<
+  typeof import('./module.js'),
+  { stableSelectors: Readonly<Record<keyof ModuleStableSelectors, string>> }
+>(combinedModule)
 
 stableSelectors.card // "knighted-card"
 ```
 
-Need a different prefix? Configure the loader’s `stableNamespace` option (or pass `--stable-namespace` to the CLI) so both runtime and generated types stay in sync.
+> [!TIP]
+> Add `&named-only` before `&types` to drop the synthetic default export while still receiving `stableSelectors`.
+
+### Default export with stable selectors
 
-## Default export with stable selectors
+_Use when you stick with default imports but also need access to the selector map._
 
 ```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined, { stableSelectors } from './module.js?knighted-css&combined&types'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import type { KnightedCssStableSelectors as ModuleStableSelectors } from './module.css.knighted-css.js'
+import * as combinedModule from './module.js?knighted-css&combined&types'
 
-const { default: Component, knightedCss } = combined as KnightedCssCombinedModule<
-  typeof import('./module.js')
->
+const {
+  default: Component,
+  knightedCss,
+  stableSelectors,
+} = asKnightedCssCombinedModule<
+  typeof import('./module.js'),
+  { stableSelectors: Readonly<Record<keyof ModuleStableSelectors, string>> }
+>(combinedModule)
 
 stableSelectors.badge // "knighted-badge"
 ```
 
-## Default and named exports with stable selectors
+### Default and named exports with stable selectors
+
+_Use when you consume every export from the module and still want the selector map._
 
 ```ts
-import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined, { stableSelectors } from './module.js?knighted-css&combined&types'
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import type { KnightedCssStableSelectors as ModuleStableSelectors } from './module.css.knighted-css.js'
+import * as combinedModule from './module.js?knighted-css&combined&types'
 
 const {
   default: Component,
   helper,
   knightedCss,
-} = combined as KnightedCssCombinedModule<typeof import('./module.js')>
+  stableSelectors,
+} = asKnightedCssCombinedModule<
+  typeof import('./module.js'),
+  { stableSelectors: Readonly<Record<keyof ModuleStableSelectors, string>> }
+>(combinedModule)
 
 stableSelectors.card // "knighted-card" (or your configured namespace)
 ```
 
-Append `&named-only` before `&types` when you want to drop the synthetic default export while still receiving `stableSelectors`.
-
 ## Key Takeaways
 
 - The loader always injects `knightedCss` alongside the module’s exports.
 - To avoid synthetic defaults (and TypeScript warnings) for modules that only expose named exports, add `&named-only` and use a namespace import.
 - Namespace imports plus `KnightedCssCombinedModule<typeof import('./module')>` work universally; default imports are optional conveniences when the source module exposes a default you actually consume.
 - Add `&types` when you also need the `stableSelectors` map. Configure the namespace globally (loader option or CLI flag) so runtime + generated types stay consistent.
+
+## When to use `KnightedCssCombinedModule`
+
+The helper type still earns its keep when you need to narrow combined results without `asKnightedCssCombinedModule` (for example, in test doubles or custom wrappers):
+
+```ts
+import type { KnightedCssCombinedModule } from '@knighted/css/loader'
+import * as moduleWithCss from './component.js?knighted-css&combined&types'
+
+type CombinedComponent = KnightedCssCombinedModule<
+  typeof import('./component.js'),
+  { stableSelectors: Readonly<Record<string, string>> }
+>
+
+const combined = moduleWithCss as CombinedComponent
+combined.knightedCss // string
+combined.stableSelectors.card // typed selector token
+```
+
+Reach for the type whenever you need to annotate combined modules manually—otherwise, the runtime helper keeps the snippets leaner.
diff --git a/docs/resolution.md b/docs/resolution.md
new file mode 100644
index 0000000..e568813
--- /dev/null
+++ b/docs/resolution.md
@@ -0,0 +1,57 @@
+# Resolution modes
+
+`@knighted/css` resolves specifiers the same way modern JavaScript tooling does, so the CSS pipeline can follow whatever graph your app already uses. This page summarizes the built-in behavior, plus the hooks you can reach for when you need to mirror bundler-specific rules.
+
+## Node-compatible graph walking
+
+The module graph walker is powered by [`oxc-resolver`](https://github.com/oxc-project/oxc-resolver), so it understands:
+
+- **Node.js exports/imports maps**: `package.json` `exports` / `imports`, including hash-prefixed entries like `#ui/button`.
+- **`tsconfig` aliases**: `baseUrl` + `paths` whether you pass a path to a config file or inline the object via `moduleGraph.tsConfig`.
+- **Extension + condition matching**: The same extension priorities and `conditionNames` your runtime/bundler would apply, configurable through `moduleGraph.extensions` and `moduleGraph.conditions`.
+
+The CLI (`css()` API) and the loader both go through this resolver, so once a specifier works in one environment it will work everywhere.
+
+## Sass-specific specifiers
+
+Sass still honors its own loader prefixes (`pkg:`, `sass:`, workspace shorthands, etc.) that never pass through Node’s resolver. When those show up, provide a custom resolver that rewrites them into absolute paths before Sass runs. See [docs/sass-import-aliases.md](./sass-import-aliases.md) for a full walkthrough and importer examples.
+
+## Custom resolver hooks
+
+### `resolver`
+
+Pass a `resolver(specifier, { cwd, from })` function to either the `css()` API or the loader to intercept specifiers before the built-in logic. Use it to:
+
+- Normalize virtual schemes (e.g. `pkg:#ui/button.scss`).
+- Delegate to your bundler’s resolver so the CSS pass sees the exact same file graph.
+- Inject synthetic files (return a `file://` URL or absolute path).
+
+The value you return wins; if you return `undefined`, `@knighted/css` falls back to tsconfig paths and Node-style resolution automatically:
+
+```ts
+import { css } from '@knighted/css'
+import createBundlerResolver from './bundler-resolver'
+
+const bundlerResolve = createBundlerResolver()
+
+await css('./src/entry.tsx', {
+  resolver: (specifier, ctx) => bundlerResolve(specifier, ctx.from ?? ctx.cwd),
+})
+```
+
+### `peerResolver`
+
+Sass, Less, vanilla-extract, and other dialects are optional peers. If your bundler already provides them (or you need to load a namespaced version), expose them through `peerResolver(name)` so `@knighted/css` never reaches into `node_modules` on its own:
+
+```ts
+await css('./src/entry.ts', {
+  peerResolver: async name => {
+    if (name === 'sass') {
+      return import('@myns/sass-runtime')
+    }
+    return import(name)
+  },
+})
+```
+
+Combine `resolver` + `peerResolver` to ensure the CSS walk stays in lockstep with your bundler’s module graph—whether you’re resolving Node `#imports`, custom Sass prefixes, or files exposed through virtual modules.
diff --git a/packages/css/README.md b/packages/css/README.md
index b35e617..acc212f 100644
--- a/packages/css/README.md
+++ b/packages/css/README.md
@@ -112,9 +112,8 @@ Refer to [docs/type-generation.md](../../docs/type-generation.md) for CLI option
 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 type { KnightedCssStableSelectors as ButtonStableSelectors } from './button.css.knighted-css.js'
 import * as buttonModule from './button.js?knighted-css&combined&types'
 
 const {

From dec476b8da7f3441dbaa7d04616641d2b4f67334 Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 10:31:37 -0600
Subject: [PATCH 2/7] chore: upgrade lint.

---
 .oxlintrc.json                      | 12 ++++-
 package-lock.json                   | 83 ++++++++++++++++-------------
 package.json                        |  2 +-
 packages/css/src/generateTypes.ts   |  1 -
 packages/css/src/loaderInternals.ts |  8 ---
 5 files changed, 57 insertions(+), 49 deletions(-)

diff --git a/.oxlintrc.json b/.oxlintrc.json
index 8c65b99..5628547 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -1,11 +1,19 @@
 {
   "$schema": "https://json.schemastore.org/oxlintrc",
-  "plugins": ["typescript", "unicorn", "oxc"],
+  "plugins": ["typescript", "unicorn", "oxc", "react", "node", "import", "vitest"],
   "env": {
     "es2022": true,
     "node": true
   },
   "globals": {
     "process": "readonly"
-  }
+  },
+  "overrides": [
+    {
+      "files": ["**/packages/css/types.d.ts"],
+      "rules": {
+        "@typescript-eslint/triple-slash-reference": "off"
+      }
+    }
+  ]
 }
diff --git a/package-lock.json b/package-lock.json
index 106a37c..4b56880 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -29,7 +29,7 @@
         "less": "^4.2.0",
         "lint-staged": "^16.2.7",
         "madge": "^8.0.0",
-        "oxlint": "^0.4.1",
+        "oxlint": "^1.35.0",
         "prettier": "^3.7.4",
         "sass": "^1.80.7",
         "tsx": "^4.19.2",
@@ -2452,9 +2452,9 @@
       ]
     },
     "node_modules/@oxlint/darwin-arm64": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/darwin-arm64/-/darwin-arm64-0.4.4.tgz",
-      "integrity": "sha512-3XqHh9uz9IROFRSJTkH81BDHERglneH4YzcchWOlkckCTHh/V5/THbTY6sA7FK3a7uJVysKJu0zgRhsyXoUNUA==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/darwin-arm64/-/darwin-arm64-1.35.0.tgz",
+      "integrity": "sha512-ieiYVHkNZPo77Hgrxav595wGS4rRNKuDNrljf+4xhwpJsddrxMpM64IQUf2IvR3MhK4FxdGzhhB6OVmGVHY5/w==",
       "cpu": [
         "arm64"
       ],
@@ -2466,9 +2466,9 @@
       ]
     },
     "node_modules/@oxlint/darwin-x64": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/darwin-x64/-/darwin-x64-0.4.4.tgz",
-      "integrity": "sha512-41/as9u+MRTmY0egr42j9Q7RMNoKEy1Uw/v+4K/5gJp1cnY99K7pGsqgbD6nMvaDbenbt8vwNSYoF2UzmUDcoQ==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/darwin-x64/-/darwin-x64-1.35.0.tgz",
+      "integrity": "sha512-1jNHu3j66X5jKySvgtE+jGtjx4ye+xioAucVTi2IuROZO6keK2YG74pnD+9FT+DpWZAtWRZGoW0r0x6aN9sEEg==",
       "cpu": [
         "x64"
       ],
@@ -2480,9 +2480,9 @@
       ]
     },
     "node_modules/@oxlint/linux-arm64-gnu": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/linux-arm64-gnu/-/linux-arm64-gnu-0.4.4.tgz",
-      "integrity": "sha512-LTOtEliKPWJzVC6qs1M0IoND0yFchWkKS6agFSmzGmfe523geC+eATq3slFvUPdSzdLAgk6v2juol7JxaI2+vg==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/linux-arm64-gnu/-/linux-arm64-gnu-1.35.0.tgz",
+      "integrity": "sha512-T1lc0UaYbTxZyqVpLfC7eipbauNG8pBpkaZEW4JGz8Y68rxTH7d9s+CF0zxUxNr5RCtcmT669RLVjQT7VrKVLg==",
       "cpu": [
         "arm64"
       ],
@@ -2494,9 +2494,9 @@
       ]
     },
     "node_modules/@oxlint/linux-arm64-musl": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/linux-arm64-musl/-/linux-arm64-musl-0.4.4.tgz",
-      "integrity": "sha512-hTmCi57YnUUxUxOWSdLEdN7IFkcJylsAZuWcVLjMCiPtTcyTeY6wPrUFqNSGLG+Gvqj/2g0aqzKt3eJBfDSOzg==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/linux-arm64-musl/-/linux-arm64-musl-1.35.0.tgz",
+      "integrity": "sha512-7Wv5Pke9kwWKFycUziSHsmi3EM0389TLzraB0KE/MArrKxx30ycwfJ5PYoMj9ERoW+Ybs0txdaOF/xJy/XyYkg==",
       "cpu": [
         "arm64"
       ],
@@ -2508,9 +2508,9 @@
       ]
     },
     "node_modules/@oxlint/linux-x64-gnu": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/linux-x64-gnu/-/linux-x64-gnu-0.4.4.tgz",
-      "integrity": "sha512-nqQr/Zj86F56EvpcbZMXEsYpUS+wpEAH1jahg70ApAEeq+EoVBqMZPv4sV1vAIy/R20f00a891fz13RGkorMnw==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/linux-x64-gnu/-/linux-x64-gnu-1.35.0.tgz",
+      "integrity": "sha512-HDMPOzyVVy+rQl3H7UOq8oGHt7m1yaiWCanlhAu4jciK8dvXeO9OG/OQd74lD/h05IcJh93pCLEJ3wWOG8hTiQ==",
       "cpu": [
         "x64"
       ],
@@ -2522,9 +2522,9 @@
       ]
     },
     "node_modules/@oxlint/linux-x64-musl": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/linux-x64-musl/-/linux-x64-musl-0.4.4.tgz",
-      "integrity": "sha512-MdyAoQgLQf/ZzneV+cCWD++6ATKWEEp1VPa61664uCYtJIKRKiavPwT5BN+nQ197Bn7n/k6pOHmo/3n8+PCFNg==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/linux-x64-musl/-/linux-x64-musl-1.35.0.tgz",
+      "integrity": "sha512-kAPBBsUOM3HQQ6n3nnZauvFR9EoXqCSoj4O3OSXXarzsRTiItNrHabVUwxeswZEc+xMzQNR0FHEWg/d4QAAWLw==",
       "cpu": [
         "x64"
       ],
@@ -2536,9 +2536,9 @@
       ]
     },
     "node_modules/@oxlint/win32-arm64": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/win32-arm64/-/win32-arm64-0.4.4.tgz",
-      "integrity": "sha512-m1azJG8XD7Po1Las7ftYFvtSUaVju1V9ic771x6/Su+8vt1Iz2pDwG7jDK+5hHbS17w8qHCYcg/IDRFHuFsOeQ==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/win32-arm64/-/win32-arm64-1.35.0.tgz",
+      "integrity": "sha512-qrpBkkOASS0WT8ra9xmBRXOEliN6D/MV9JhI/68lFHrtLhfFuRwg4AjzjxrCWrQCnQ0WkvAVpJzu73F4ICLYZw==",
       "cpu": [
         "arm64"
       ],
@@ -2550,9 +2550,9 @@
       ]
     },
     "node_modules/@oxlint/win32-x64": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/@oxlint/win32-x64/-/win32-x64-0.4.4.tgz",
-      "integrity": "sha512-4ZyCtwNHqfOPzSPoEUHuFxcYCxRGMTB9ZmDJCVZGVbxwE462FPz6IfoinEqaiesgnuaBqN78CkLqW5kfhnxm+A==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/@oxlint/win32-x64/-/win32-x64-1.35.0.tgz",
+      "integrity": "sha512-yPFcj6umrhusnG/kMS5wh96vblsqZ0kArQJS+7kEOSJDrH+DsFWaDCsSRF8U6gmSmZJ26KVMU3C3TMpqDN4M1g==",
       "cpu": [
         "x64"
       ],
@@ -8788,29 +8788,38 @@
       }
     },
     "node_modules/oxlint": {
-      "version": "0.4.4",
-      "resolved": "https://registry.npmjs.org/oxlint/-/oxlint-0.4.4.tgz",
-      "integrity": "sha512-YF4rEASRYWCJBaCd0yDavYJ1qCA5H2l6piXlAeDnIKjqKHQ7V3Hwu5w5gIkgZne73iXFe6baqcMSlZNdNlqCeA==",
+      "version": "1.35.0",
+      "resolved": "https://registry.npmjs.org/oxlint/-/oxlint-1.35.0.tgz",
+      "integrity": "sha512-QDX1aUgaiqznkGfTM2qHwva2wtKqhVoqPSVXrnPz+yLUhlNadikD3QRuRtppHl7WGuy3wG6nKAuR8lash3aWSg==",
       "dev": true,
       "license": "MIT",
       "bin": {
+        "oxc_language_server": "bin/oxc_language_server",
         "oxlint": "bin/oxlint"
       },
       "engines": {
-        "node": ">=14.*"
+        "node": "^20.19.0 || >=22.12.0"
       },
       "funding": {
         "url": "https://github.com/sponsors/Boshen"
       },
       "optionalDependencies": {
-        "@oxlint/darwin-arm64": "0.4.4",
-        "@oxlint/darwin-x64": "0.4.4",
-        "@oxlint/linux-arm64-gnu": "0.4.4",
-        "@oxlint/linux-arm64-musl": "0.4.4",
-        "@oxlint/linux-x64-gnu": "0.4.4",
-        "@oxlint/linux-x64-musl": "0.4.4",
-        "@oxlint/win32-arm64": "0.4.4",
-        "@oxlint/win32-x64": "0.4.4"
+        "@oxlint/darwin-arm64": "1.35.0",
+        "@oxlint/darwin-x64": "1.35.0",
+        "@oxlint/linux-arm64-gnu": "1.35.0",
+        "@oxlint/linux-arm64-musl": "1.35.0",
+        "@oxlint/linux-x64-gnu": "1.35.0",
+        "@oxlint/linux-x64-musl": "1.35.0",
+        "@oxlint/win32-arm64": "1.35.0",
+        "@oxlint/win32-x64": "1.35.0"
+      },
+      "peerDependencies": {
+        "oxlint-tsgolint": ">=0.10.0"
+      },
+      "peerDependenciesMeta": {
+        "oxlint-tsgolint": {
+          "optional": true
+        }
       }
     },
     "node_modules/p-limit": {
diff --git a/package.json b/package.json
index c33cd52..990ffd8 100644
--- a/package.json
+++ b/package.json
@@ -48,7 +48,7 @@
     "less": "^4.2.0",
     "lint-staged": "^16.2.7",
     "madge": "^8.0.0",
-    "oxlint": "^0.4.1",
+    "oxlint": "^1.35.0",
     "prettier": "^3.7.4",
     "sass": "^1.80.7",
     "tsx": "^4.19.2",
diff --git a/packages/css/src/generateTypes.ts b/packages/css/src/generateTypes.ts
index 2e49df9..56e3648 100644
--- a/packages/css/src/generateTypes.ts
+++ b/packages/css/src/generateTypes.ts
@@ -107,7 +107,6 @@ function getImportMetaUrl(): string | undefined {
   }
 }
 
-const PACKAGE_ROOT = resolvePackageRoot()
 const SELECTOR_REFERENCE = '.knighted-css'
 const SELECTOR_MODULE_SUFFIX = '.knighted-css.ts'
 
diff --git a/packages/css/src/loaderInternals.ts b/packages/css/src/loaderInternals.ts
index 8576793..815f8a2 100644
--- a/packages/css/src/loaderInternals.ts
+++ b/packages/css/src/loaderInternals.ts
@@ -47,14 +47,6 @@ export function hasQueryFlag(query: string | null | undefined, flag: string): bo
   return entries.some(part => isQueryFlag(part, flag))
 }
 
-function safeDecode(value: string): string {
-  try {
-    return decodeURIComponent(value)
-  } catch {
-    return value
-  }
-}
-
 export function shouldForwardDefaultExport(request: string): boolean {
   const [pathPart] = request.split('?')
   if (!pathPart) return true

From 54072f210adbadcae92c2f037e815f06bcd3c1be Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 10:41:53 -0600
Subject: [PATCH 3/7] docs: contributing.

---
 CONTRIBUTING.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..f986020
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing to @knighted/css
+
+Thanks for spending time on the Knighted CSS suite! This document highlights the conventions that are hardest to infer from the codebase so you can ship fixes without guesswork.
+
+## Local setup
+
+1. Use Node 22+ and npm (the repo scripts assume npm).
+2. Install dependencies from the repo root: `npm install`.
+3. Run lint and tests before sending a PR:
+   - `npm run lint` (oxlint across every package)
+   - `npm test` (delegates to each package's test runner)
+
+## File naming policy
+
+We enforce naming gradually with `unicorn/filename-case` so existing camelCase modules keep working while new code stays consistent.
+
+- **New files**: default to kebab-case (e.g., `module-info.ts`). PascalCase is reserved for files that export React-style components or top-level docs such as `README.md`.
+- **Legacy folders**: some directories (especially `packages/css/src/**`) still contain camelCase files. They remain whitelisted in `.oxlintrc.json`. When you touch one of those files, feel free to rename it to kebab-case in a dedicated commit and then tighten the ignore glob.
+- **Special cases**: directories such as `__snapshots__` and `.husky/_` intentionally keep underscores—leave those alone.
+
+## Type stub directories
+
+The CSS package ships two `types-stub` directories on purpose:
+
+- `packages/css/src/types-stub/` is the source stub checked into git. The entire repo references this file during development so editors and TypeScript builds succeed before generated selectors exist.
+- `packages/css/types-stub/` is a build artifact copied by `packages/css/scripts/copy-types-stub.js` during `npm run build`. It **must** stay in git because npm publishes from `packages/css/` directly; removing it would strip the placeholder declarations that consumers need on fresh installs.
+
+When editing the stub, always update the version under `src/types-stub/` and let the copy script mirror it.
+
+## Type entrypoint strategy
+
+`packages/css/types.d.ts` currently uses triple-slash references to pull in `loader-queries.d.ts` and the stub above. This is intentional for the entire 1.x line so downstream TypeScript consumers enjoy stable behavior. We silence the `typescript-eslint/triple-slash-reference` warning via `.oxlintrc.json`. When we design 2.0.0 we will switch to ESM-style imports and remove that override—please keep that in mind if you are touching the type entrypoint.
+
+## Pull request checklist
+
+- Follow the naming rules above for any new files.
+- Confirm `npm run lint` emits zero warnings.
+- Describe any behavioral changes in the relevant package README or docs (e.g., `docs/combined-queries.md`).
+- If you touch the type stub or generator, call it out explicitly in the PR so we can double-check publish artifacts.
+
+Happy hacking!

From ab003e6320aa42b1c2ecd107802cb3a3d385378b Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 10:53:00 -0600
Subject: [PATCH 4/7] chore: add filename lint rule.

---
 .oxlintrc.json | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/.oxlintrc.json b/.oxlintrc.json
index 5628547..0d62f5f 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -8,12 +8,97 @@
   "globals": {
     "process": "readonly"
   },
+  "rules": {
+    "unicorn/filename-case": [
+      "error",
+      {
+        "cases": {
+          "camelCase": true,
+          "kebabCase": true,
+          "pascalCase": true
+        }
+      }
+    ]
+  },
   "overrides": [
     {
       "files": ["**/packages/css/types.d.ts"],
       "rules": {
         "@typescript-eslint/triple-slash-reference": "off"
       }
+    },
+    {
+      "files": ["packages/css/src/**/*.{ts,tsx,js,jsx}", "packages/css/src/**/*.d.ts"],
+      "rules": {
+        "unicorn/filename-case": [
+          "error",
+          {
+            "cases": { "camelCase": true }
+          }
+        ]
+      }
+    },
+    {
+      "files": ["packages/css/scripts/**/*.js"],
+      "rules": {
+        "unicorn/filename-case": [
+          "error",
+          {
+            "cases": { "kebabCase": true }
+          }
+        ]
+      }
+    },
+    {
+      "files": ["packages/css/test/**/*.ts"],
+      "rules": {
+        "unicorn/filename-case": [
+          "error",
+          {
+            "cases": { "camelCase": true }
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "packages/css/dist/**",
+        "packages/css/types-stub/**",
+        "packages/css/stable/**",
+        "packages/css/coverage/**"
+      ],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
+    },
+    {
+      "files": ["packages/css/src/loader-helpers.ts", "packages/css/src/types-stub/**"],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
+    },
+    {
+      "files": [
+        "packages/css/test/__snapshots__/**",
+        "packages/css/test/fixtures/**",
+        "packages/css/test/helpers/**"
+      ],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
+    },
+    {
+      "files": [
+        "packages/css/test/css-walker.test.ts",
+        "packages/css/test/loader-helpers-runtime.test.ts",
+        "packages/css/test/loader-queries.types.ts",
+        "packages/css/test/loader_rspack.test.ts",
+        "packages/css/test/loader_unit.test.ts",
+        "packages/css/test/stable-mixins.test.ts"
+      ],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
     }
   ]
 }

From a1cc8b6b51be6ba9c12b1ce4fc2ca187e2384c55 Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 11:03:12 -0600
Subject: [PATCH 5/7] chore: rename test files.

---
 .oxlintrc.json                                      | 13 -------------
 .../test/{css-walker.test.ts => cssWalker.test.ts}  |  0
 ...runtime.test.ts => loaderHelpersRuntime.test.ts} |  0
 ...ader-queries.types.ts => loaderQueries.types.ts} |  0
 .../{loader_rspack.test.ts => loaderRspack.test.ts} |  0
 .../{loader_unit.test.ts => loaderUnit.test.ts}     |  0
 .../{stable-mixins.test.ts => stableMixins.test.ts} |  0
 7 files changed, 13 deletions(-)
 rename packages/css/test/{css-walker.test.ts => cssWalker.test.ts} (100%)
 rename packages/css/test/{loader-helpers-runtime.test.ts => loaderHelpersRuntime.test.ts} (100%)
 rename packages/css/test/{loader-queries.types.ts => loaderQueries.types.ts} (100%)
 rename packages/css/test/{loader_rspack.test.ts => loaderRspack.test.ts} (100%)
 rename packages/css/test/{loader_unit.test.ts => loaderUnit.test.ts} (100%)
 rename packages/css/test/{stable-mixins.test.ts => stableMixins.test.ts} (100%)

diff --git a/.oxlintrc.json b/.oxlintrc.json
index 0d62f5f..e94279c 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -86,19 +86,6 @@
       "rules": {
         "unicorn/filename-case": "off"
       }
-    },
-    {
-      "files": [
-        "packages/css/test/css-walker.test.ts",
-        "packages/css/test/loader-helpers-runtime.test.ts",
-        "packages/css/test/loader-queries.types.ts",
-        "packages/css/test/loader_rspack.test.ts",
-        "packages/css/test/loader_unit.test.ts",
-        "packages/css/test/stable-mixins.test.ts"
-      ],
-      "rules": {
-        "unicorn/filename-case": "off"
-      }
     }
   ]
 }
diff --git a/packages/css/test/css-walker.test.ts b/packages/css/test/cssWalker.test.ts
similarity index 100%
rename from packages/css/test/css-walker.test.ts
rename to packages/css/test/cssWalker.test.ts
diff --git a/packages/css/test/loader-helpers-runtime.test.ts b/packages/css/test/loaderHelpersRuntime.test.ts
similarity index 100%
rename from packages/css/test/loader-helpers-runtime.test.ts
rename to packages/css/test/loaderHelpersRuntime.test.ts
diff --git a/packages/css/test/loader-queries.types.ts b/packages/css/test/loaderQueries.types.ts
similarity index 100%
rename from packages/css/test/loader-queries.types.ts
rename to packages/css/test/loaderQueries.types.ts
diff --git a/packages/css/test/loader_rspack.test.ts b/packages/css/test/loaderRspack.test.ts
similarity index 100%
rename from packages/css/test/loader_rspack.test.ts
rename to packages/css/test/loaderRspack.test.ts
diff --git a/packages/css/test/loader_unit.test.ts b/packages/css/test/loaderUnit.test.ts
similarity index 100%
rename from packages/css/test/loader_unit.test.ts
rename to packages/css/test/loaderUnit.test.ts
diff --git a/packages/css/test/stable-mixins.test.ts b/packages/css/test/stableMixins.test.ts
similarity index 100%
rename from packages/css/test/stable-mixins.test.ts
rename to packages/css/test/stableMixins.test.ts

From 2652e9d8a9cd4bd5be2f32530623ac7fb226b6b1 Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 11:15:56 -0600
Subject: [PATCH 6/7] chore: update lint-staged cycles.

---
 package.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/package.json b/package.json
index 990ffd8..e6e6ba3 100644
--- a/package.json
+++ b/package.json
@@ -20,7 +20,7 @@
     "lint": "oxlint packages",
     "prettier": "prettier --write .",
     "prettier:check": "prettier --check .",
-    "check:cycles": "madge packages/css/src --ts-config packages/css/tsconfig.json --extensions ts,tsx --circular",
+    "check:cycles": "madge packages/css/src --ts-config packages/css/tsconfig.json --extensions ts,tsx,js,jsx,mjs,cjs --circular && madge packages/playwright/src --ts-config packages/playwright/tsconfig.json --extensions ts,tsx,js,jsx,mjs,cjs --circular",
     "preview:e2e": "npm run preview -w @knighted/css-playwright-fixture",
     "check-types": "npm run check-types -w @knighted/css && npm run check-types -w @knighted/css-playwright-fixture",
     "clean:deps": "find . -name node_modules -type d -prune -exec rm -rf {} +",
@@ -66,7 +66,7 @@
     "singleQuote": true
   },
   "lint-staged": {
-    "*": "npm run check:cycles",
+    "{packages/css/src,packages/playwright/src}/**/*.{ts,tsx,js,jsx,mjs,cjs}": "npm run check:cycles",
     "*.{js,jsx,ts,tsx,mjs,cjs,cts,mts}": "oxlint",
     "*.{js,jsx,ts,tsx,mjs,cjs,cts,mts,json,md,css,scss,html}": "prettier --check"
   },

From 92fffe2c5f4d2beda717e987a04807d78ed47e12 Mon Sep 17 00:00:00 2001
From: KCM <knightedcodemonkey@gmail.com>
Date: Wed, 24 Dec 2025 11:17:26 -0600
Subject: [PATCH 7/7] ci: check cycles.

---
 .github/workflows/ci.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2cc8b60..2a8dc52 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -34,6 +34,8 @@ jobs:
           path: npm-debug.log
       - name: Lint
         run: npm run lint
+      - name: Check Cycles
+        run: npm run check:cycles
       - name: Test
         run: npm test
       - name: Report Coverage