test: different import specifiers e2e. (#33)

Author: knightedcodemonkey

README.md

@@ -113,15 +113,25 @@ Need the module exports, `knightedCss`, and a runtime `stableSelectors` map from
 
 ```ts
 import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import combined, { stableSelectors } from './button.js?knighted-css&combined&types'
-
-const { default: Button, knightedCss } = combined as KnightedCssCombinedModule<
-  typeof import('./button.js')
->
+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
 

docs/combined-queries.md

@@ -5,6 +5,12 @@ This document summarizes how `?knighted-css&combined` behaves for different modu
 > [!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.
+
+> [!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                                                                                                                      |
@@ -37,7 +43,8 @@ import type { KnightedCssCombinedModule } from '@knighted/css/loader'
 import combined from './module.js?knighted-css&combined'
 
 const { default: Component, knightedCss } = combined as KnightedCssCombinedModule<
-  typeof import('./module.js')
+  typeof import('./module.js'),
+  { stableSelectors: typeof stableSelectors }
 >
 ```
 
@@ -51,7 +58,10 @@ const {
   default: Component,
   helper,
   knightedCss,
-} = combined as KnightedCssCombinedModule<typeof import('./module.js')>
+} = combined as KnightedCssCombinedModule<
+  typeof import('./module.js'),
+  { stableSelectors: typeof stableSelectors }
+>
 ```
 
 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`.

docs/loader.md

@@ -40,15 +40,29 @@ Need the component exports **and** the compiled CSS from a single import? Use `?
 
 ```ts
 import type { KnightedCssCombinedModule } from '@knighted/css/loader'
-import buttonModule from './button.js?knighted-css&combined'
-
-const { default: Button, knightedCss } = buttonModule as KnightedCssCombinedModule<
-  typeof import('./button.js')
->
+import { asKnightedCssCombinedModule } from '@knighted/css/loader-helpers'
+import * as buttonModule from './button.js?knighted-css&combined'
+
+const { default: Button, knightedCss } =
+  asKnightedCssCombinedModule<typeof import('./button.js')>(buttonModule)
+
+// Need to describe additional loader-injected exports (for example, `stableSelectors` when
+// using `?knighted-css&combined&types`)? Pass a second generic:
+const {
+  default: ButtonWithSelectors,
+  knightedCss: buttonCss,
+  stableSelectors,
+} = asKnightedCssCombinedModule<
+  typeof import('./button.js'),
+  { stableSelectors: Record<string, string> }
+>(buttonModule)
 ```
 
 Append `&named-only` (alias: `&no-default`) if you never consume the default export. Refer to [docs/combined-queries.md](./combined-queries.md) for the full matrix of query flags and destructuring patterns.
 
+> [!TIP]
+> `@knighted/css/loader-helpers` ships the `asKnightedCssCombinedModule` helper in isolation so you can safely import it from browser bundles. This keeps the heavy loader implementation (and its Node dependencies) out of client builds.
+
 ### Runtime selectors (`&types`)
 
 When you need the runtime `stableSelectors` map alongside `knightedCss`, append `&types` to either the plain or combined import:

packages/css/loader-queries.d.ts

@@ -19,7 +19,12 @@ declare module '*?knighted-css&types' {
  * TypeScript cannot infer the underlying module automatically, so consumers can
  * import the default export and narrow it with `KnightedCssCombinedModule<typeof import('./file')>`.
  */
-type KnightedCssCombinedModule<TModule> = TModule & { knightedCss: string }
+type KnightedCssCombinedExtras = Readonly<Record<string, unknown>>
+
+type KnightedCssCombinedModule<
+  TModule,
+  TExtras extends KnightedCssCombinedExtras = Record<never, never>,
+> = TModule & TExtras & { knightedCss: string }
 
 declare module '*?knighted-css&combined' {
   const combined: KnightedCssCombinedModule<Record<string, unknown>>

packages/css/package.json

@@ -10,6 +10,9 @@
       "loader": [
         "./dist/loader.d.ts"
       ],
+      "loader-helpers": [
+        "./dist/loader-helpers.d.ts"
+      ],
       "loader-queries": [
         "./loader-queries.d.ts"
       ],
@@ -32,6 +35,11 @@
       "import": "./dist/loader.js",
       "require": "./dist/cjs/loader.cjs"
     },
+    "./loader-helpers": {
+      "types": "./dist/loader-helpers.d.ts",
+      "import": "./dist/loader-helpers.js",
+      "require": "./dist/cjs/loader-helpers.cjs"
+    },
     "./loader-queries": {
       "types": "./loader-queries.d.ts",
       "default": "./loader-queries.d.ts"

packages/css/src/loader-helpers.ts

@@ -0,0 +1,11 @@
+import type { KnightedCssCombinedModule } from './loader.js'
+
+// Keep helper side-effect free so bundlers can safely tree-shake it into web targets.
+type KnightedCssCombinedExtras = Readonly<Record<string, unknown>>
+
+export function asKnightedCssCombinedModule<
+  TModule,
+  TExtras extends KnightedCssCombinedExtras = Record<never, never>,
+>(module: unknown): KnightedCssCombinedModule<TModule, TExtras> {
+  return module as KnightedCssCombinedModule<TModule, TExtras>
+}

packages/css/src/loader.ts

@@ -18,9 +18,15 @@ import {
 import { buildStableSelectorsLiteral } from './stableSelectorsLiteral.js'
 import { resolveStableNamespace } from './stableNamespace.js'
 
-export type KnightedCssCombinedModule<TModule> = TModule & {
-  knightedCss: string
-}
+type KnightedCssCombinedExtras = Readonly<Record<string, unknown>>
+
+export type KnightedCssCombinedModule<
+  TModule,
+  TExtras extends KnightedCssCombinedExtras = Record<never, never>,
+> = TModule &
+  TExtras & {
+    knightedCss: string
+  }
 
 export interface KnightedCssVanillaOptions {
   transformToEsm?: boolean
@@ -50,6 +56,7 @@ const loader: LoaderDefinitionFunction<KnightedCssLoaderOptions> = async functio
         namespace: resolvedNamespace,
         resourcePath: this.resourcePath,
         emitWarning: message => emitKnightedWarning(this, message),
+        target: 'js',
       })
     : undefined
   const injection = buildInjection(css, {
@@ -131,6 +138,7 @@ export const pitch: PitchLoaderDefinitionFunction<KnightedCssLoaderOptions> =
               namespace: resolvedNamespace,
               resourcePath: this.resourcePath,
               emitWarning: message => emitKnightedWarning(this, message),
+              target: 'js',
             })
           : undefined
         return createCombinedModule(request, css, {

packages/css/src/stableSelectorsLiteral.ts

@@ -7,21 +7,22 @@ export interface StableSelectorsLiteralResult {
   selectorMap: Map<string, string>
 }
 
+type StableSelectorsLiteralTarget = 'ts' | 'js'
+
 export function buildStableSelectorsLiteral(options: {
   css: string
   namespace: string
   resourcePath: string
   emitWarning: (message: string) => void
+  target?: StableSelectorsLiteralTarget
 }): StableSelectorsLiteralResult {
+  const target: StableSelectorsLiteralTarget = options.target ?? 'ts'
   const trimmedNamespace = options.namespace.trim()
   if (!trimmedNamespace) {
     options.emitWarning(
       `stableSelectors requested for ${options.resourcePath} but "stableNamespace" resolved to an empty value.`,
     )
-    return {
-      literal: 'export const stableSelectors = {} as const;\n',
-      selectorMap: new Map<string, string>(),
-    }
+    return finalizeLiteral(new Map<string, string>(), target)
   }
 
   const selectorMap = collectStableSelectors(
@@ -34,9 +35,17 @@ export function buildStableSelectorsLiteral(options: {
       `stableSelectors requested for ${options.resourcePath} but no selectors matched namespace "${trimmedNamespace}".`,
     )
   }
+  return finalizeLiteral(selectorMap, target)
+}
 
+function finalizeLiteral(
+  selectorMap: Map<string, string>,
+  target: StableSelectorsLiteralTarget,
+): StableSelectorsLiteralResult {
+  const formatted = formatStableSelectorMap(selectorMap)
+  const suffix = target === 'ts' ? ' as const' : ''
   return {
-    literal: `export const stableSelectors = ${formatStableSelectorMap(selectorMap)} as const;\n`,
+    literal: `export const stableSelectors = ${formatted}${suffix};\n`,
     selectorMap,
   }
 }

packages/css/test/loader_unit.test.ts

@@ -174,7 +174,7 @@ test('loader emits stableSelectors export when ?types flag is present', async ()
   assert.match(output, /export const stableSelectors = /)
   assert.match(
     output,
-    /export const stableSelectors = Object\.freeze\(\{\s*"demo": "knighted-demo",\s*"icon": "knighted-icon"\s*\}\) as const;/,
+    /export const stableSelectors = Object\.freeze\(\{\s*"demo": "knighted-demo",\s*"icon": "knighted-icon"\s*\}\);/,
     'should emit map of detected selectors using default namespace',
   )
 })
@@ -195,7 +195,7 @@ test('loader respects stableNamespace loader option', async () => {
 
   assert.match(
     output,
-    /export const stableSelectors = Object\.freeze\(\{\s*"card": "acme-card"\s*\}\) as const;/,
+    /export const stableSelectors = Object\.freeze\(\{\s*"card": "acme-card"\s*\}\);/,
     'should scope selector discovery to provided namespace',
   )
 })
@@ -218,7 +218,7 @@ test('loader warns when stableNamespace option resolves to empty value', async (
     ),
   )
 
-  assert.match(output, /export const stableSelectors = \{\} as const;/)
+  assert.match(output, /export const stableSelectors = Object\.freeze\(\{\}\);/)
   assert.equal(warnings.length, 1)
   assert.match(
     warnings[0] ?? '',
@@ -273,7 +273,7 @@ test('pitch injects stableSelectors export when combined types query is used', a
   const combinedOutput = String(result ?? '')
   assert.match(
     combinedOutput,
-    /export const stableSelectors = Object\.freeze\(\{\s*"demo": "knighted-demo",\s*"icon": "knighted-icon"\s*\}\) as const;/,
+    /export const stableSelectors = Object\.freeze\(\{\s*"demo": "knighted-demo",\s*"icon": "knighted-icon"\s*\}\);/,
     'combined proxy should forward stable selector map',
   )
 })

packages/css/test/stableSelectorsLiteral.test.ts

@@ -14,11 +14,26 @@ test('buildStableSelectorsLiteral warns when namespace is empty', () => {
     resourcePath: 'demo.css',
     emitWarning: message => warnings.push(message),
   })
-  assert.equal(result.literal.trim(), 'export const stableSelectors = {} as const;')
+  assert.equal(
+    result.literal.trim(),
+    'export const stableSelectors = Object.freeze({}) as const;',
+  )
   assert.equal(result.selectorMap.size, 0)
   assert.equal(warnings.length, 1)
 })
 
+test('buildStableSelectorsLiteral emits JS-friendly literal when requested', () => {
+  const result = buildStableSelectorsLiteral({
+    css: '.knighted-card {}',
+    namespace: 'knighted',
+    resourcePath: 'demo.css',
+    emitWarning: () => {},
+    target: 'js',
+  })
+  assert.match(result.literal, /export const stableSelectors = Object\.freeze/)
+  assert.ok(!result.literal.includes('as const'))
+})
+
 test('collectStableSelectors captures selectors and formats map output', () => {
   const { collectStableSelectors, formatStableSelectorMap } =
     __stableSelectorsLiteralInternals