@knighted/jsx 1.3.0 → 1.3.2

package/README.md

@@ -18,9 +18,9 @@ A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-p
 - [React runtime](#react-runtime-reactjsx)
 - [Loader integration](#loader-integration)
 - [Node / SSR usage](#node--ssr-usage)
-- [Next.js integration](#nextjs-integration)
 - [Browser usage](#browser-usage)
-- [Testing & demos](#testing)
+- [TypeScript plugin](docs/ts-plugin.md)
+- [Component testing](docs/testing.md)
 - [CLI setup](docs/cli.md)
 
 ## Installation
@@ -30,7 +30,7 @@ npm install @knighted/jsx
 ```
 
 > [!IMPORTANT]
-> This package is ESM-only and targets browsers or ESM-aware bundlers. `require()` is not supported; use native `import`/`<script type="module">` and a DOM-like environment.
+> `@knighted/jsx` ships as ESM-only. The dual-mode `.cjs` artifacts we build internally are not published.
 
 > [!NOTE]
 > Planning to use the React runtime (`@knighted/jsx/react`)? Install `react@>=18` and `react-dom@>=18` alongside this package so the helper can create elements and render them through ReactDOM.
@@ -94,6 +94,51 @@ createRoot(document.getElementById('root')!).render(reactJsx`<${App} />`)
 
 The React runtime shares the same template semantics as `jsx`, except it returns React elements (via `React.createElement`) so you can embed other React components with `<${MyComponent} />` and use hooks/state as usual. The helper lives in a separate subpath so DOM-only consumers never pay the React dependency cost.
 
+### DOM-specific props
+
+- `style` accepts either a string or an object. Object values handle CSS custom properties (`--token`) automatically.
+- `class` and `className` both work and can be strings or arrays.
+- Event handlers use the `on<Event>` naming convention (e.g. `onClick`).
+- `ref` supports callback refs as well as mutable `{ current }` objects.
+- `dangerouslySetInnerHTML` expects an object with an `__html` field, mirroring React.
+
+### Fragments & SVG
+
+Use JSX fragments (`<>...</>`) for multi-root templates. SVG trees automatically switch to the `http://www.w3.org/2000/svg` namespace once they enter an `<svg>` tag, and fall back inside `<foreignObject>`.
+
+### Interpolations and components
+
+- `${...}` works exactly like JSX braces: drop expressions anywhere (text, attributes, spreads, conditionals) and the runtime keeps the original syntax. Text nodes do not need extra wrapping—`Count is ${value}` already works.
+- Interpolated values can be primitives, DOM nodes, arrays/iterables, other `jsx` trees, or component functions. Resolve Promises before passing them in.
+- Inline components are just functions/classes you interpolate as the tag name; they receive props plus optional `children` and can return anything `jsx` accepts.
+
+```ts
+const Button = ({ variant = 'primary' }) => {
+  let count = 3
+
+  return jsx`
+    <button
+      data-variant=${variant}
+      onClick=${() => {
+        count += 1
+        console.log(`Count is now ${count}`)
+      }}
+    >
+      Count is ${count}
+    </button>
+  `
+}
+
+const view = jsx`
+  <section>
+    <p>Inline components can manage their own state.</p>
+    <${Button} variant="ghost" />
+  </section>
+`
+
+document.body.append(view)
+```
+
 ## Loader integration
 
 Use the published loader entry (`@knighted/jsx/loader`) when you want your bundler to rewrite tagged template literals at build time. The loader finds every ` jsx`` ` (and, by default, ` reactJsx`` ` ) invocation, rebuilds the template with real JSX semantics, and hands back transformed source that can run in any environment.
@@ -121,24 +166,9 @@ export default {
 }
 ```
 
-Pair the loader with your existing TypeScript/JSX transpiler (SWC, Babel, Rspack’s builtin loader, etc.) so regular React components and the tagged templates can live side by side. The demo fixture under `test/fixtures/rspack-app` shows a full setup that mixes Lit and React, and there is also a standalone walkthrough at [morganney/jsx-loader-demo](https://github.com/morganney/jsx-loader-demo):
-
-```sh
-npm run build
-npm run setup:wasm
-npm run build:fixture
-```
-
-Then point a static server at the fixture root (which serves `index.html` plus the bundled `dist/hybrid.js` and `dist/reactMode.js`) to see it in a browser:
-
-```sh
-# Serve the rspack fixture from the repo root
-npx http-server test/fixtures/rspack-app -p 4173
-```
-
-Visit `http://localhost:4173` (or whichever port you pick) to interact with both the Lit + React hybrid demo and the React-mode bundle.
+Pair the loader with your existing TypeScript/JSX transpiler (SWC, Babel, Rspack’s builtin loader, etc.) so regular React components and the tagged templates can live side by side.
 
-Need a deeper dive into loader behavior and options? Check out [`src/loader/README.md`](src/loader/README.md) for a full walkthrough.
+Need a deeper dive into loader behavior and options? Check out [`src/loader/README.md`](src/loader/README.md). There is also a standalone walkthrough at [morganney/jsx-loader-demo](https://github.com/morganney/jsx-loader-demo).
 
 ## Node / SSR usage
 
@@ -174,126 +204,7 @@ console.log(shell.outerHTML)
 
 This repository ships a ready-to-run fixture under `test/fixtures/node-ssr` that uses the Node entry to render a Lit shell plus a React subtree through `ReactDOMServer.renderToString`. Run `npm run build` once to emit `dist/`, then execute `npm run demo:node-ssr` to log the generated markup.
 
-## Next.js integration
-
-> [!IMPORTANT]
-> Next already compiles `.tsx/.jsx` files, so you do not need this helper to author regular components. The loader only adds value when you want to reuse the tagged template runtime during SSR—mixing DOM nodes built by `jsx` with React markup, rendering shared utilities on the server, or processing tagged templates outside the usual component pipeline.
-
-Next (and Remix/other Webpack-based SSR stacks) can run the loader by adding a post-loader to the framework config so the template tags are rewritten after SWC/Babel transpilation. The fixture under `test/fixtures/next-app` ships a complete example that mixes DOM and React helpers during SSR so you can pre-render DOM snippets (for emails, HTML streams, CMS content, etc.) while still returning React components from your pages. The important bits live in `next.config.mjs`:
-
-```js
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const repoRoot = path.resolve(__dirname, '../../..')
-const distDir = path.join(repoRoot, 'dist')
-
-export default {
-  output: 'export',
-  webpack(config) {
-    config.resolve.alias = {
-      ...(config.resolve.alias ?? {}),
-      '@knighted/jsx': path.join(distDir, 'index.js'),
-      '@knighted/jsx/react': path.join(distDir, 'react/index.js'),
-    }
-
-    config.module.rules.push({
-      test: /\.[jt]sx?$/,
-      include: path.join(__dirname, 'pages'),
-      enforce: 'post',
-      use: [{ loader: path.join(distDir, 'loader/jsx.js') }],
-    })
-
-    return config
-  },
-}
-```
-
-Inside `pages/index.tsx` you can freely mix the helpers. The snippet below uses `jsx` on the server to prebuild a DOM fragment and then injects that HTML alongside a normal React component on the client:
-
-```ts
-import type { GetServerSideProps } from 'next'
-import { jsx } from '@knighted/jsx'
-import { reactJsx } from '@knighted/jsx/react'
-
-const buildDomShell = () =>
-  jsx`
-    <section data-kind="dom-runtime">
-      <h2>DOM runtime</h2>
-      <p>Rendered as static HTML on the server</p>
-    </section>
-  `
-
-export const getServerSideProps: GetServerSideProps = async () => {
-  return {
-    props: {
-      domShell: buildDomShell().outerHTML,
-    },
-  }
-}
-
-const ReactBadge = () =>
-  reactJsx`
-    <button type="button">React badge</button>
-  `
-
-type PageProps = { domShell: string }
-
-export default function Page({ domShell }: PageProps) {
-  return reactJsx`
-    <main>
-      <${ReactBadge} />
-      <div dangerouslySetInnerHTML={${{ __html: domShell }}}></div>
-    </main>
-  `
-}
-```
-
-Build the fixture locally with `npx next build test/fixtures/next-app` (or run `npx vitest run test/next-fixture.test.ts`) to verify the integration end to end. You can adapt the same pattern in `app/` routes, API handlers, or server actions whenever you need DOM output generated by the tagged template runtime.
-
-### Interpolations
-
-- All dynamic values are provided through standard template literal expressions (`${...}`) and map to JSX exactly where they appear. Interpolations used as text children no longer need an extra `{...}` wrapper—the runtime automatically recognizes placeholders inside text segments (so `Count is ${value}` just works). Use the usual JSX braces when the syntax requires them (`className={${value}}`, `{...props}`, conditionals, etc.).
-- Every expression can be any JavaScript value: primitives, arrays/iterables, DOM nodes, functions, other `jsx` results, or custom component references.
-- Async values (Promises) are not supported. Resolve them before passing into the template.
-
-### Components
-
-You can inline components by interpolating the function used for the tag name. The component receives a props object plus the optional `children` prop and can return anything that `jsx` can render (DOM nodes, strings, fragments, other arrays, ...).
-
-```ts
-const Button = ({ children, variant = 'primary' }) => {
-  const el = document.createElement('button')
-  el.dataset.variant = variant
-  el.append(children ?? '')
-  return el
-}
-
-const label = 'Tap me'
-
-const view = jsx`
-  <section>
-    <${Button} variant="ghost">
-      ${label}
-    </${Button}>
-  </section>
-`
-
-document.body.append(view)
-```
-
-### Fragments & SVG
-
-Use JSX fragments (`<>...</>`) for multi-root templates. SVG trees automatically switch to the `http://www.w3.org/2000/svg` namespace once they enter an `<svg>` tag, and fall back inside `<foreignObject>`.
-
-### DOM-specific props
-
-- `style` accepts either a string or an object. Object values handle CSS custom properties (`--token`) automatically.
-- `class` and `className` both work and can be strings or arrays.
-- Event handlers use the `on<Event>` naming convention (e.g. `onClick`).
-- `ref` supports callback refs as well as mutable `{ current }` objects.
-- `dangerouslySetInnerHTML` expects an object with an `__html` field, mirroring React.
+See how to [integrate with Next.js](./docs/nextjs-integration.md).
 
 ## Browser usage
 
@@ -302,26 +213,26 @@ When you are not using a bundler, load the module directly from a CDN that under
 ```html
 <script type="module">
   import { jsx } from 'https://esm.sh/@knighted/jsx'
+  import { reactJsx } from 'https://esm.sh/@knighted/jsx/react'
+  import { useState } from 'https://esm.sh/react@19'
+  import { createRoot } from 'https://esm.sh/react-dom@19/client'
 
-  const message = jsx`<p>Hello from the browser</p>`
-  document.body.append(message)
-</script>
-```
-
-If you are building locally with Vite/Rollup/Webpack make sure the WASM binding is installable so the bundler can resolve `@oxc-parser/binding-wasm32-wasi` (details below).
+  const reactMount = jsx`<div data-kind="react-mount" />`
 
-### Installing the WASM binding locally
-
-`@oxc-parser/binding-wasm32-wasi` publishes with `"cpu": ["wasm32"]`, so npm/yarn/pnpm skip it on macOS and Linux unless you override the platform guard. Run the helper script after cloning (or whenever you clean `node_modules`) to pull the binding into place for the Vite demo and any other local bundler builds:
+  const CounterButton = () => {
+    const [count, setCount] = useState(0)
+    return reactJsx`
+      <button type="button" onClick={${() => setCount(value => value + 1)}}>
+        Count is ${count}
+      </button>
+    `
+  }
 
-```sh
-npm run setup:wasm
+  document.body.append(reactMount)
+  createRoot(reactMount).render(reactJsx`<${CounterButton} />`)
+</script>
 ```
 
-The script downloads the published tarball via `npm pack`, extracts it into `node_modules/@oxc-parser/binding-wasm32-wasi`, and removes the temporary archive so your lockfile stays untouched. If you need to test a different binding build, set `WASM_BINDING_PACKAGE` before running the script (for example, `WASM_BINDING_PACKAGE=@oxc-parser/binding-wasm32-wasi@0.100.0 npm run setup:wasm`).
-
-Prefer the manual route? You can still run `npm_config_ignore_platform=true npm install --no-save @oxc-parser/binding-wasm32-wasi@^0.99.0`, but the script above replicates the vendored behavior with less ceremony.
-
 ### Lite bundle entry
 
 If you already run this package through your own bundler you can trim a few extra kilobytes by importing the minified entries:
@@ -335,40 +246,6 @@ import { reactJsx as nodeReactJsx } from '@knighted/jsx/node/react/lite'
 
 Each lite subpath ships the same API as its standard counterpart but is pre-minified and scoped to just that runtime (DOM, React, Node DOM, or Node React). Swap them in when you want the smallest possible bundles; otherwise the default exports keep working as-is.
 
-## Testing
-
-Run the Vitest suite (powered by jsdom) to exercise the DOM runtime and component support:
-
-```sh
-npm run test
-```
-
-Tests live in `test/jsx.test.ts` and cover DOM props/events, custom components, fragments, and iterable children so you can see exactly how the template tag is meant to be used.
-
-Need full end-to-end coverage? The Playwright suite boots the CDN demo (`examples/esm-demo.html`) and the loader-backed Rspack fixture to verify nested trees, sibling structures, and interop with Lit/React:
-
-```sh
-npm run test:e2e
-```
-
-> [!NOTE]
-> The e2e script builds the library, installs the WASM parser binding, bundles the loader fixture, and then runs `playwright test`. Make sure Playwright browsers are installed locally (`npx playwright install --with-deps chromium`).
-
-## Browser demo / Vite build
-
-This repo ships with a ready-to-run Vite demo under `examples/browser` that bundles the library (make sure you have installed the WASM binding via the command above first). Use it for a full end-to-end verification in a real browser (the demo imports `@knighted/jsx/lite` so you can confirm the lighter entry behaves identically):
-
-```sh
-# Start a dev server at http://localhost:5173
-npm run dev
-
-# Produce a production Rollup build and preview it
-npm run build:demo
-npm run preview
-```
-
-For a zero-build verification of the lite bundle, open `examples/esm-demo-lite.html` locally (double-click or run `open examples/esm-demo-lite.html`) or visit the deployed GitHub Pages build produced by `.github/workflows/deploy-demo.yml` (it serves that same lite HTML demo).
-
 ## Limitations
 
 - Requires a DOM-like environment (it throws when `document` is missing).

package/dist/cjs/cli/init.cjs

@@ -26,6 +26,21 @@ const tar_1 = require("tar");
 const DEFAULT_BINDING_SPEC = process.env.WASM_BINDING_PACKAGE ?? '@oxc-parser/binding-wasm32-wasi@^0.99.0';
 const RUNTIME_DEPS = ['@napi-rs/wasm-runtime', '@emnapi/runtime', '@emnapi/core'];
 const SUPPORTED_PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+// Node emits a noisy ExperimentalWarning whenever the WASI shim loads; silence just that message.
+const WASI_WARNING_SNIPPET = 'WASI is an experimental feature';
+const LOADER_CONFIG_EXAMPLE = [
+    '// Example loader entry to drop into your bundler rules array:',
+    '{',
+    "  loader: '@knighted/jsx/loader',",
+    '  options: {',
+    "    tags: ['jsx', 'reactJsx'],",
+    '    tagModes: {',
+    "      reactJsx: 'react',",
+    '    },',
+    '  },',
+    '}',
+].join('\n');
+suppressExperimentalWasiWarning();
 function parseArgs(argv) {
     const options = {
         cwd: process.cwd(),
@@ -114,11 +129,11 @@ function ensurePackageJson(cwd) {
         throw new Error('No package.json found. Run this inside a project with package.json.');
     }
 }
-function runNpmPack(spec, cwd, dryRun, verbose) {
+function runNpmPack(spec, cwd, dryRun, verbose, execFn = node_child_process_1.execFileSync) {
     logVerbose(`> npm pack ${spec}`, verbose);
     if (dryRun)
         return `${spec.replace(/\W+/g, '_')}.tgz`;
-    const output = (0, node_child_process_1.execFileSync)('npm', ['pack', spec], {
+    const output = execFn('npm', ['pack', spec], {
         cwd,
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'inherit'],
@@ -133,9 +148,9 @@ function parsePackageName(spec) {
     const [, name, version] = match;
     return { name, version };
 }
-async function installBinding(spec, cwd, dryRun, verbose) {
+async function installBinding(spec, cwd, dryRun, verbose, pack = runNpmPack) {
     const { name, version } = parsePackageName(spec);
-    const tarballName = runNpmPack(spec, cwd, dryRun, verbose);
+    const tarballName = pack(spec, cwd, dryRun, verbose);
     const tarballPath = node_path_1.default.resolve(cwd, tarballName);
     const targetDir = node_path_1.default.resolve(cwd, 'node_modules', ...name.split('/'));
     log(`> Installing ${spec} into ${targetDir}`);
@@ -147,7 +162,7 @@ async function installBinding(spec, cwd, dryRun, verbose) {
     }
     return { targetDir, tarballPath: dryRun ? undefined : tarballPath, name, version };
 }
-function installRuntimeDeps(pm, deps, cwd, dryRun, verbose) {
+function installRuntimeDeps(pm, deps, cwd, dryRun, verbose, spawner = node_child_process_1.spawnSync) {
     const missing = deps.filter(dep => !isDependencyInstalled(dep, cwd));
     if (missing.length === 0) {
         log('> Runtime dependencies already present; skipping install');
@@ -162,7 +177,7 @@ function installRuntimeDeps(pm, deps, cwd, dryRun, verbose) {
     const [command, args] = commands[pm];
     logVerbose(`> ${command} ${args.join(' ')}`, verbose);
     if (!dryRun) {
-        const result = (0, node_child_process_1.spawnSync)(command, args, { cwd, stdio: 'inherit' });
+        const result = spawner(command, args, { cwd, stdio: 'inherit' });
         if (result.status !== 0) {
             throw new Error(`Failed to install runtime dependencies with ${pm}`);
         }
@@ -194,11 +209,11 @@ function persistBindingSpec(cwd, name, version, dryRun, verbose) {
         node_fs_1.default.writeFileSync(pkgPath, `${JSON.stringify(pkgJson, null, 2)}\n`, 'utf8');
     }
 }
-async function verifyBinding(name, cwd, verbose) {
+async function verifyBinding(name, cwd, verbose, importer = specifier => import(specifier)) {
     const requireFromCwd = (0, node_module_1.createRequire)(node_path_1.default.join(cwd, 'package.json'));
     const resolved = requireFromCwd.resolve(name);
     logVerbose(`> Resolved ${name} to ${resolved}`, verbose);
-    const imported = await import((0, node_url_1.pathToFileURL)(resolved).href);
+    const imported = await importer((0, node_url_1.pathToFileURL)(resolved).href);
     if (!imported) {
         throw new Error(`Imported ${name} is empty; verification failed`);
     }
@@ -229,27 +244,30 @@ async function maybeHandleConfigPrompt(skipConfig, force) {
         return;
     }
     log('> Loader assistance is interactive and not applied automatically yet. See docs at docs/cli.md for next steps.');
+    log('> Example loader config (webpack / rspack):');
+    console.log(LOADER_CONFIG_EXAMPLE);
 }
-async function main() {
-    const options = parseArgs(process.argv.slice(2));
-    ensurePackageJson(options.cwd);
-    const packageManager = detectPackageManager(options.cwd, options.packageManager);
-    log(`> Using package manager: ${packageManager}`);
-    const installedRuntimeDeps = installRuntimeDeps(packageManager, RUNTIME_DEPS, options.cwd, options.dryRun, options.verbose);
-    const binding = await installBinding(options.wasmPackage, options.cwd, options.dryRun, options.verbose);
-    persistBindingSpec(options.cwd, binding.name, binding.version, options.dryRun, options.verbose);
+async function main(overrides = {}) {
+    const { parseArgs: parseArgsImpl = parseArgs, ensurePackageJson: ensurePackageJsonImpl = ensurePackageJson, detectPackageManager: detectPackageManagerImpl = detectPackageManager, installRuntimeDeps: installRuntimeDepsImpl = installRuntimeDeps, installBinding: installBindingImpl = installBinding, persistBindingSpec: persistBindingSpecImpl = persistBindingSpec, verifyBinding: verifyBindingImpl = verifyBinding, maybeHandleConfigPrompt: maybeHandleConfigPromptImpl = maybeHandleConfigPrompt, log: logImpl = log, } = overrides;
+    const options = parseArgsImpl(process.argv.slice(2));
+    ensurePackageJsonImpl(options.cwd);
+    const packageManager = detectPackageManagerImpl(options.cwd, options.packageManager);
+    logImpl(`> Using package manager: ${packageManager}`);
+    const installedRuntimeDeps = installRuntimeDepsImpl(packageManager, RUNTIME_DEPS, options.cwd, options.dryRun, options.verbose);
+    const binding = await installBindingImpl(options.wasmPackage, options.cwd, options.dryRun, options.verbose);
+    persistBindingSpecImpl(options.cwd, binding.name, binding.version, options.dryRun, options.verbose);
     let resolvedPath;
     if (!options.dryRun) {
-        resolvedPath = await verifyBinding(binding.name, options.cwd, options.verbose);
-        log(`> Verified ${binding.name} at ${resolvedPath}`);
+        resolvedPath = await verifyBindingImpl(binding.name, options.cwd, options.verbose);
+        logImpl(`> Verified ${binding.name} at ${resolvedPath}`);
     }
-    await maybeHandleConfigPrompt(options.skipConfig, options.force);
-    log('\nDone!');
-    log(`- Binding: ${binding.name}${binding.version ? `@${binding.version}` : ''}`);
-    log(`- Target: ${binding.targetDir}`);
-    log(`- Runtime deps installed: ${installedRuntimeDeps.join(', ') || 'none (already present)'}`);
+    await maybeHandleConfigPromptImpl(options.skipConfig, options.force);
+    logImpl('\nDone!');
+    logImpl(`- Binding: ${binding.name}${binding.version ? `@${binding.version}` : ''}`);
+    logImpl(`- Target: ${binding.targetDir}`);
+    logImpl(`- Runtime deps installed: ${installedRuntimeDeps.join(', ') || 'none (already present)'}`);
     if (resolvedPath)
-        log(`- Verified import: ${resolvedPath}`);
+        logImpl(`- Verified import: ${resolvedPath}`);
 }
 if (process.env.KNIGHTED_JSX_CLI_TEST !== '1') {
     main().catch(error => {
@@ -257,3 +275,17 @@ if (process.env.KNIGHTED_JSX_CLI_TEST !== '1') {
         process.exitCode = 1;
     });
 }
+function suppressExperimentalWasiWarning() {
+    const originalEmitWarning = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...args) => {
+        const [typeMaybe] = args;
+        const message = typeof warning === 'string' ? warning : warning.message;
+        const name = typeof warning === 'string' ? undefined : warning.name;
+        const type = typeof typeMaybe === 'string' ? typeMaybe : undefined;
+        if (message.includes(WASI_WARNING_SNIPPET) &&
+            (name === 'ExperimentalWarning' || type === 'ExperimentalWarning')) {
+            return;
+        }
+        return originalEmitWarning(warning, ...args);
+    });
+}

package/dist/cjs/cli/init.d.cts

@@ -1,3 +1,4 @@
+import { execFileSync, spawnSync } from 'node:child_process';
 declare const SUPPORTED_PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
 type PackageManager = (typeof SUPPORTED_PACKAGE_MANAGERS)[number];
 type CliOptions = {
@@ -10,9 +11,10 @@ type CliOptions = {
     wasmPackage: string;
 };
 declare function parseArgs(argv: string[]): CliOptions;
+declare function log(message: string): void;
 declare function detectPackageManager(cwd: string, explicit?: PackageManager): PackageManager;
 declare function ensurePackageJson(cwd: string): void;
-declare function runNpmPack(spec: string, cwd: string, dryRun: boolean, verbose: boolean): string;
+declare function runNpmPack(spec: string, cwd: string, dryRun: boolean, verbose: boolean, execFn?: typeof execFileSync): string;
 declare function parsePackageName(spec: string): {
     name: string;
     version: undefined;
@@ -20,17 +22,30 @@ declare function parsePackageName(spec: string): {
     name: string;
     version: string;
 };
-declare function installBinding(spec: string, cwd: string, dryRun: boolean, verbose: boolean): Promise<{
+type PackFunction = (spec: string, cwd: string, dryRun: boolean, verbose: boolean) => string;
+declare function installBinding(spec: string, cwd: string, dryRun: boolean, verbose: boolean, pack?: PackFunction): Promise<{
     targetDir: string;
     tarballPath?: string;
     name: string;
     version?: string;
 }>;
-declare function installRuntimeDeps(pm: PackageManager, deps: string[], cwd: string, dryRun: boolean, verbose: boolean): string[];
+declare function installRuntimeDeps(pm: PackageManager, deps: string[], cwd: string, dryRun: boolean, verbose: boolean, spawner?: typeof spawnSync): string[];
 declare function isDependencyInstalled(dep: string, cwd: string): boolean;
 declare function persistBindingSpec(cwd: string, name: string, version: string | undefined, dryRun: boolean, verbose: boolean): void;
-declare function verifyBinding(name: string, cwd: string, verbose: boolean): Promise<string>;
+type BindingImporter = (specifier: string) => Promise<unknown>;
+declare function verifyBinding(name: string, cwd: string, verbose: boolean, importer?: BindingImporter): Promise<string>;
 declare function promptYesNo(prompt: string, defaultValue: boolean, force: boolean): Promise<boolean>;
 declare function maybeHandleConfigPrompt(skipConfig: boolean, force: boolean): Promise<void>;
-declare function main(): Promise<void>;
+type MainDeps = {
+    parseArgs: typeof parseArgs;
+    ensurePackageJson: typeof ensurePackageJson;
+    detectPackageManager: typeof detectPackageManager;
+    installRuntimeDeps: typeof installRuntimeDeps;
+    installBinding: typeof installBinding;
+    persistBindingSpec: typeof persistBindingSpec;
+    verifyBinding: typeof verifyBinding;
+    maybeHandleConfigPrompt: typeof maybeHandleConfigPrompt;
+    log: typeof log;
+};
+declare function main(overrides?: Partial<MainDeps>): Promise<void>;
 export { parseArgs, detectPackageManager, ensurePackageJson, runNpmPack, parsePackageName, installBinding, installRuntimeDeps, isDependencyInstalled, persistBindingSpec, verifyBinding, promptYesNo, maybeHandleConfigPrompt, main, };

package/dist/cli/init.d.ts

@@ -1,3 +1,4 @@
+import { execFileSync, spawnSync } from 'node:child_process';
 declare const SUPPORTED_PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
 type PackageManager = (typeof SUPPORTED_PACKAGE_MANAGERS)[number];
 type CliOptions = {
@@ -10,9 +11,10 @@ type CliOptions = {
     wasmPackage: string;
 };
 declare function parseArgs(argv: string[]): CliOptions;
+declare function log(message: string): void;
 declare function detectPackageManager(cwd: string, explicit?: PackageManager): PackageManager;
 declare function ensurePackageJson(cwd: string): void;
-declare function runNpmPack(spec: string, cwd: string, dryRun: boolean, verbose: boolean): string;
+declare function runNpmPack(spec: string, cwd: string, dryRun: boolean, verbose: boolean, execFn?: typeof execFileSync): string;
 declare function parsePackageName(spec: string): {
     name: string;
     version: undefined;
@@ -20,17 +22,30 @@ declare function parsePackageName(spec: string): {
     name: string;
     version: string;
 };
-declare function installBinding(spec: string, cwd: string, dryRun: boolean, verbose: boolean): Promise<{
+type PackFunction = (spec: string, cwd: string, dryRun: boolean, verbose: boolean) => string;
+declare function installBinding(spec: string, cwd: string, dryRun: boolean, verbose: boolean, pack?: PackFunction): Promise<{
     targetDir: string;
     tarballPath?: string;
     name: string;
     version?: string;
 }>;
-declare function installRuntimeDeps(pm: PackageManager, deps: string[], cwd: string, dryRun: boolean, verbose: boolean): string[];
+declare function installRuntimeDeps(pm: PackageManager, deps: string[], cwd: string, dryRun: boolean, verbose: boolean, spawner?: typeof spawnSync): string[];
 declare function isDependencyInstalled(dep: string, cwd: string): boolean;
 declare function persistBindingSpec(cwd: string, name: string, version: string | undefined, dryRun: boolean, verbose: boolean): void;
-declare function verifyBinding(name: string, cwd: string, verbose: boolean): Promise<string>;
+type BindingImporter = (specifier: string) => Promise<unknown>;
+declare function verifyBinding(name: string, cwd: string, verbose: boolean, importer?: BindingImporter): Promise<string>;
 declare function promptYesNo(prompt: string, defaultValue: boolean, force: boolean): Promise<boolean>;
 declare function maybeHandleConfigPrompt(skipConfig: boolean, force: boolean): Promise<void>;
-declare function main(): Promise<void>;
+type MainDeps = {
+    parseArgs: typeof parseArgs;
+    ensurePackageJson: typeof ensurePackageJson;
+    detectPackageManager: typeof detectPackageManager;
+    installRuntimeDeps: typeof installRuntimeDeps;
+    installBinding: typeof installBinding;
+    persistBindingSpec: typeof persistBindingSpec;
+    verifyBinding: typeof verifyBinding;
+    maybeHandleConfigPrompt: typeof maybeHandleConfigPrompt;
+    log: typeof log;
+};
+declare function main(overrides?: Partial<MainDeps>): Promise<void>;
 export { parseArgs, detectPackageManager, ensurePackageJson, runNpmPack, parsePackageName, installBinding, installRuntimeDeps, isDependencyInstalled, persistBindingSpec, verifyBinding, promptYesNo, maybeHandleConfigPrompt, main, };

package/dist/cli/init.js

@@ -10,6 +10,20 @@ import { extract } from 'tar';
 var DEFAULT_BINDING_SPEC = process.env.WASM_BINDING_PACKAGE ?? "@oxc-parser/binding-wasm32-wasi@^0.99.0";
 var RUNTIME_DEPS = ["@napi-rs/wasm-runtime", "@emnapi/runtime", "@emnapi/core"];
 var SUPPORTED_PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+var WASI_WARNING_SNIPPET = "WASI is an experimental feature";
+var LOADER_CONFIG_EXAMPLE = [
+  "// Example loader entry to drop into your bundler rules array:",
+  "{",
+  "  loader: '@knighted/jsx/loader',",
+  "  options: {",
+  "    tags: ['jsx', 'reactJsx'],",
+  "    tagModes: {",
+  "      reactJsx: 'react',",
+  "    },",
+  "  },",
+  "}"
+].join("\n");
+suppressExperimentalWasiWarning();
 function parseArgs(argv) {
   const options = {
     cwd: process.cwd(),
@@ -97,10 +111,10 @@ function ensurePackageJson(cwd) {
     throw new Error("No package.json found. Run this inside a project with package.json.");
   }
 }
-function runNpmPack(spec, cwd, dryRun, verbose) {
+function runNpmPack(spec, cwd, dryRun, verbose, execFn = execFileSync) {
   logVerbose(`> npm pack ${spec}`, verbose);
   if (dryRun) return `${spec.replace(/\W+/g, "_")}.tgz`;
-  const output = execFileSync("npm", ["pack", spec], {
+  const output = execFn("npm", ["pack", spec], {
     cwd,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "inherit"]
@@ -114,9 +128,9 @@ function parsePackageName(spec) {
   const [, name, version] = match;
   return { name, version };
 }
-async function installBinding(spec, cwd, dryRun, verbose) {
+async function installBinding(spec, cwd, dryRun, verbose, pack = runNpmPack) {
   const { name, version } = parsePackageName(spec);
-  const tarballName = runNpmPack(spec, cwd, dryRun, verbose);
+  const tarballName = pack(spec, cwd, dryRun, verbose);
   const tarballPath = path.resolve(cwd, tarballName);
   const targetDir = path.resolve(cwd, "node_modules", ...name.split("/"));
   log(`> Installing ${spec} into ${targetDir}`);
@@ -128,7 +142,7 @@ async function installBinding(spec, cwd, dryRun, verbose) {
   }
   return { targetDir, tarballPath: dryRun ? void 0 : tarballPath, name, version };
 }
-function installRuntimeDeps(pm, deps, cwd, dryRun, verbose) {
+function installRuntimeDeps(pm, deps, cwd, dryRun, verbose, spawner = spawnSync) {
   const missing = deps.filter((dep) => !isDependencyInstalled(dep, cwd));
   if (missing.length === 0) {
     log("> Runtime dependencies already present; skipping install");
@@ -143,7 +157,7 @@ function installRuntimeDeps(pm, deps, cwd, dryRun, verbose) {
   const [command, args] = commands[pm];
   logVerbose(`> ${command} ${args.join(" ")}`, verbose);
   if (!dryRun) {
-    const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+    const result = spawner(command, args, { cwd, stdio: "inherit" });
     if (result.status !== 0) {
       throw new Error(`Failed to install runtime dependencies with ${pm}`);
     }
@@ -175,11 +189,11 @@ function persistBindingSpec(cwd, name, version, dryRun, verbose) {
 `, "utf8");
   }
 }
-async function verifyBinding(name, cwd, verbose) {
+async function verifyBinding(name, cwd, verbose, importer = (specifier) => import(specifier)) {
   const requireFromCwd = createRequire(path.join(cwd, "package.json"));
   const resolved = requireFromCwd.resolve(name);
   logVerbose(`> Resolved ${name} to ${resolved}`, verbose);
-  const imported = await import(pathToFileURL(resolved).href);
+  const imported = await importer(pathToFileURL(resolved).href);
   if (!imported) {
     throw new Error(`Imported ${name} is empty; verification failed`);
   }
@@ -213,26 +227,39 @@ async function maybeHandleConfigPrompt(skipConfig, force) {
   log(
     "> Loader assistance is interactive and not applied automatically yet. See docs at docs/cli.md for next steps."
   );
+  log("> Example loader config (webpack / rspack):");
+  console.log(LOADER_CONFIG_EXAMPLE);
 }
-async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  ensurePackageJson(options.cwd);
-  const packageManager = detectPackageManager(options.cwd, options.packageManager);
-  log(`> Using package manager: ${packageManager}`);
-  const installedRuntimeDeps = installRuntimeDeps(
+async function main(overrides = {}) {
+  const {
+    parseArgs: parseArgsImpl = parseArgs,
+    ensurePackageJson: ensurePackageJsonImpl = ensurePackageJson,
+    detectPackageManager: detectPackageManagerImpl = detectPackageManager,
+    installRuntimeDeps: installRuntimeDepsImpl = installRuntimeDeps,
+    installBinding: installBindingImpl = installBinding,
+    persistBindingSpec: persistBindingSpecImpl = persistBindingSpec,
+    verifyBinding: verifyBindingImpl = verifyBinding,
+    maybeHandleConfigPrompt: maybeHandleConfigPromptImpl = maybeHandleConfigPrompt,
+    log: logImpl = log
+  } = overrides;
+  const options = parseArgsImpl(process.argv.slice(2));
+  ensurePackageJsonImpl(options.cwd);
+  const packageManager = detectPackageManagerImpl(options.cwd, options.packageManager);
+  logImpl(`> Using package manager: ${packageManager}`);
+  const installedRuntimeDeps = installRuntimeDepsImpl(
     packageManager,
     RUNTIME_DEPS,
     options.cwd,
     options.dryRun,
     options.verbose
   );
-  const binding = await installBinding(
+  const binding = await installBindingImpl(
     options.wasmPackage,
     options.cwd,
     options.dryRun,
     options.verbose
   );
-  persistBindingSpec(
+  persistBindingSpecImpl(
     options.cwd,
     binding.name,
     binding.version,
@@ -241,17 +268,17 @@ async function main() {
   );
   let resolvedPath;
   if (!options.dryRun) {
-    resolvedPath = await verifyBinding(binding.name, options.cwd, options.verbose);
-    log(`> Verified ${binding.name} at ${resolvedPath}`);
+    resolvedPath = await verifyBindingImpl(binding.name, options.cwd, options.verbose);
+    logImpl(`> Verified ${binding.name} at ${resolvedPath}`);
   }
-  await maybeHandleConfigPrompt(options.skipConfig, options.force);
-  log("\nDone!");
-  log(`- Binding: ${binding.name}${binding.version ? `@${binding.version}` : ""}`);
-  log(`- Target: ${binding.targetDir}`);
-  log(
+  await maybeHandleConfigPromptImpl(options.skipConfig, options.force);
+  logImpl("\nDone!");
+  logImpl(`- Binding: ${binding.name}${binding.version ? `@${binding.version}` : ""}`);
+  logImpl(`- Target: ${binding.targetDir}`);
+  logImpl(
     `- Runtime deps installed: ${installedRuntimeDeps.join(", ") || "none (already present)"}`
   );
-  if (resolvedPath) log(`- Verified import: ${resolvedPath}`);
+  if (resolvedPath) logImpl(`- Verified import: ${resolvedPath}`);
 }
 if (process.env.KNIGHTED_JSX_CLI_TEST !== "1") {
   main().catch((error) => {
@@ -262,5 +289,18 @@ if (process.env.KNIGHTED_JSX_CLI_TEST !== "1") {
     process.exitCode = 1;
   });
 }
+function suppressExperimentalWasiWarning() {
+  const originalEmitWarning = process.emitWarning.bind(process);
+  process.emitWarning = ((warning, ...args) => {
+    const [typeMaybe] = args;
+    const message = typeof warning === "string" ? warning : warning.message;
+    const name = typeof warning === "string" ? void 0 : warning.name;
+    const type = typeof typeMaybe === "string" ? typeMaybe : void 0;
+    if (message.includes(WASI_WARNING_SNIPPET) && (name === "ExperimentalWarning" || type === "ExperimentalWarning")) {
+      return;
+    }
+    return originalEmitWarning(warning, ...args);
+  });
+}
 
 export { detectPackageManager, ensurePackageJson, installBinding, installRuntimeDeps, isDependencyInstalled, main, maybeHandleConfigPrompt, parseArgs, parsePackageName, persistBindingSpec, promptYesNo, runNpmPack, verifyBinding };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
     "jsx runtime",