feat: support package.json imports.

Author: knightedcodemonkey

README.md

@@ -24,7 +24,7 @@ I needed a single source of truth for UI components that could drop into both li
 ## 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` conditions, and extension aliasing (e.g., `.css.js` → `.css.ts`) are honored without wiring up a bundler.
+- 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.
@@ -172,6 +172,9 @@ export async function render(url: string) {
 
 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.
+
 ```ts
 import { ResolverFactory } from 'enhanced-resolve'
 import { css } from '@knighted/css'

docs/loader.md

@@ -34,6 +34,9 @@ export default {
 }
 ```
 
+> [!NOTE]
+> The loader shares the same auto-configured `oxc-resolver` as the standalone `css()` API, so hash-prefixed specifiers declared under `package.json#imports` (for example, `#ui/button`) resolve without additional options.
+
 ### Combined imports
 
 Need the component exports **and** the compiled CSS from a single import? Use `?knighted-css&combined` and narrow the result with `KnightedCssCombinedModule` to keep TypeScript happy:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-rc.14",
+  "version": "1.0.0-rc.15",
   "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",

packages/css/package.json

@@ -266,7 +266,10 @@ function normalizeSpecifier(raw: string): string {
   if (!trimmed || trimmed.startsWith('\0')) {
     return ''
   }
-  const queryIndex = trimmed.search(/[?#]/)
+  const querySearchOffset = trimmed.startsWith('#') ? 1 : 0
+  const remainder = trimmed.slice(querySearchOffset)
+  const queryMatchIndex = remainder.search(/[?#]/)
+  const queryIndex = queryMatchIndex === -1 ? -1 : querySearchOffset + queryMatchIndex
   const withoutQuery = queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex)
   if (!withoutQuery) {
     return ''
@@ -394,9 +397,7 @@ function createResolverFactory(
     options.extensionAlias = extensionAlias
   }
   const tsconfigOption = resolveResolverTsconfig(graphOptions?.tsConfig, cwd)
-  if (tsconfigOption) {
-    options.tsconfig = tsconfigOption
-  }
+  options.tsconfig = tsconfigOption ?? 'auto'
   return new ResolverFactory(options)
 }
 

packages/css/src/moduleGraph.ts

@@ -205,3 +205,49 @@ import '@blocks/panel'
     await project.cleanup()
   }
 })
+
+test('collectStyleImports keeps hash-prefixed specifiers intact', async () => {
+  const project = await createProject('knighted-module-graph-imports-hash-')
+  try {
+    await project.writeFile(
+      'package.json',
+      JSON.stringify(
+        {
+          name: 'hash-imports',
+          type: 'module',
+          imports: {
+            '#ui/*': './src/ui/*',
+          },
+        },
+        null,
+        2,
+      ),
+    )
+    await project.writeFile('src/ui/button.scss', '.button { color: hotpink; }')
+    await project.writeFile(
+      'src/ui/button.js',
+      `import './button.scss'
+export const Button = () => null
+`,
+    )
+    await project.writeFile(
+      'src/entry.ts',
+      `import { Button } from '#ui/button.js'
+void Button
+`,
+    )
+
+    const styles = await collectStyleImports(project.file('src/entry.ts'), {
+      cwd: project.root,
+      styleExtensions: ['.scss'],
+      filter: () => true,
+    })
+
+    assert.deepEqual(
+      await realpathAll(styles),
+      await realpathAll([project.file('src/ui/button.scss')]),
+    )
+  } finally {
+    await project.cleanup()
+  }
+})

packages/css/test/moduleGraph.test.ts

@@ -0,0 +1,8 @@
+# @knighted/css Playwright fixtures
+
+This package builds the demo surface that Playwright pokes during CI. It now renders two scenarios side by side:
+
+- **Lit + React wrapper**: the existing showcase that exercises vanilla CSS, Sass/Less, vanilla-extract, and the combined loader queries.
+- **Hash-imports workspace demo**: a minimal npm workspace under `src/hash-imports-workspace/` where `apps/hash-import-demo` uses `package.json#imports` (hash-prefixed specifiers) to resolve UI modules provided by a sibling workspace package. The fixture proves that `@knighted/css/loader` and the standalone `css()` API honor `#workspace/*` specifiers with zero extra configuration.
+
+Run `npm run test -- --project=chromium hash-imports.spec.ts` from this directory to rebuild the preview bundle and execute only the hash-imports checks. The default `npm test` target still runs the full matrix (chromium on CI plus the webpack + SSR builds).

packages/playwright/README.md

@@ -15,7 +15,7 @@
     "pretest": "npm run build"
   },
   "dependencies": {
-    "@knighted/css": "1.0.0-rc.14",
+    "@knighted/css": "1.0.0-rc.15",
     "@knighted/jsx": "^1.4.1",
     "lit": "^3.2.1",
     "react": "^19.0.0",

packages/playwright/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@hash-imports/demo",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#workspace/ui/*": "./src/workspace-bridge/*"
+  }
+}

packages/playwright/src/hash-imports-workspace/apps/hash-import-demo/package.json

@@ -0,0 +1,3 @@
+export const HASH_IMPORTS_SECTION_ID = 'hash-imports-workspace'
+export const HASH_IMPORTS_CARD_TEST_ID = 'hash-imports-card'
+export const HASH_IMPORTS_BADGE_TEST_ID = 'hash-imports-badge'