@knighted/jsx 1.3.1 → 1.4.0

package/README.md

@@ -18,10 +18,10 @@ 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)
+- [TypeScript plugin](docs/ts-plugin.md)
+- [TypeScript guide](docs/typescript.md)
 - [Component testing](docs/testing.md)
-- [Testing & demos](#testing)
 - [CLI setup](docs/cli.md)
 
 ## Installation
@@ -31,7 +31,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.
@@ -95,6 +95,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.
@@ -122,24 +167,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):
+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.
 
-```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.
-
-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
 
@@ -175,126 +205,46 @@ 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
+See how to [integrate with Next.js](./docs/nextjs-integration.md).
 
-> [!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'
+## TypeScript integration
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-const repoRoot = path.resolve(__dirname, '../../..')
-const distDir = path.join(repoRoot, 'dist')
+The [`@knighted/jsx-ts-plugin`](docs/ts-plugin.md) keeps DOM (`jsx`) and React (`reactJsx`) templates type-safe with a single config block. The plugin maps each helper to the right mode by default, so you can mix DOM nodes and React components in the same file without juggling multiple plugin entries.
 
-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
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@knighted/jsx-ts-plugin",
+        "tagModes": {
+          "jsx": "dom",
+          "reactJsx": "react",
+        },
+      },
+    ],
   },
 }
 ```
 
-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:
+- Choose **TypeScript: Select TypeScript Version → Use Workspace Version** in VS Code so the plugin loads from `node_modules`.
+- Run `tsc --noEmit` (or your build step) to surface the same diagnostics your editor shows.
+- Set `jsxImportSource` to `@knighted/jsx` when compiling `.tsx` helpers. The package publishes the `@knighted/jsx/jsx-runtime` module TypeScript expects. The runtime export exists solely for diagnostics and will throw if you call it at execution time—switch back to tagged templates before shipping code.
+- Drop `/* @jsx-dom */` or `/* @jsx-react */` immediately before a tagged template when you need a one-off override.
+- Import the `JsxRenderable` helper type from `@knighted/jsx` whenever you annotate DOM-facing utilities without the plugin:
 
-```ts
-import type { GetServerSideProps } from 'next'
-import { jsx } from '@knighted/jsx'
-import { reactJsx } from '@knighted/jsx/react'
+  ```ts
+  import type { JsxRenderable } from '@knighted/jsx'
 
-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>
-  `
-}
-```
+  const coerceToDom = (value: unknown): JsxRenderable => value ?? ''
+  const view = jsx`<section>${coerceToDom(data)}</section>`
+  ```
 
-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
+> [!TIP]
+> Full `tsconfig` examples (single config or split React + DOM helper projects) live in [docs/typescript.md](docs/typescript.md).
 
-- `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.
+Head over to [docs/ts-plugin.md](docs/ts-plugin.md) for deeper guidance, advanced options, and troubleshooting tips.
 
 ## Browser usage
 
@@ -303,26 +253,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:
@@ -336,44 +286,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
-
-Looking for guidance on testing your own components with `jsx` or `reactJsx`? See
-[docs/testing.md](docs/testing.md) for DOM and React runtime examples. The commands
-below cover the library's internal test suites.
-
-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/cjs/jsx-runtime.cjs

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Fragment = void 0;
+exports.jsx = jsx;
+exports.jsxs = jsxs;
+exports.jsxDEV = jsxDEV;
+const runtimeModuleId = '@knighted/jsx/jsx-runtime';
+const fragmentSymbolDescription = `${runtimeModuleId}::Fragment`;
+const runtimeNotAvailable = () => {
+    throw new Error(`The automatic JSX runtime is only published for TypeScript diagnostics. ` +
+        `Render DOM nodes through the jsx tagged template exported by @knighted/jsx instead.`);
+};
+exports.Fragment = Symbol.for(fragmentSymbolDescription);
+function jsx(_, __, ___) {
+    return runtimeNotAvailable();
+}
+function jsxs(_, __, ___) {
+    return runtimeNotAvailable();
+}
+function jsxDEV(_, __, ___, ____, _____, ______) {
+    return runtimeNotAvailable();
+}

package/dist/cjs/jsx-runtime.d.cts

@@ -0,0 +1,32 @@
+import type { JsxRenderable } from './jsx.cjs';
+export declare const Fragment: unique symbol;
+export declare function jsx(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxs(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxDEV(_: unknown, __?: unknown, ___?: unknown, ____?: boolean, _____?: unknown, ______?: unknown): JsxRenderable;
+type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | null | undefined;
+};
+type AriaAttributes = {
+    [K in `aria-${string}`]?: string | number | boolean | null | undefined;
+};
+type EventHandlers<T extends EventTarget> = {
+    [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<string & K>}`]?: (event: GlobalEventHandlersEventMap[K]) => void;
+};
+type ElementProps<Tag extends keyof HTMLElementTagNameMap> = Partial<HTMLElementTagNameMap[Tag]> & EventHandlers<HTMLElementTagNameMap[Tag]> & DataAttributes & AriaAttributes & {
+    class?: string;
+    className?: string;
+    style?: string | Record<string, string | number>;
+    ref?: ((value: HTMLElementTagNameMap[Tag]) => void) | {
+        current: HTMLElementTagNameMap[Tag] | null;
+    };
+    children?: JsxRenderable | JsxRenderable[];
+};
+declare global {
+    namespace JSX {
+        type Element = JsxRenderable;
+        type IntrinsicElements = {
+            [Tag in keyof HTMLElementTagNameMap]: ElementProps<Tag>;
+        };
+    }
+}
+export {};

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/dist/jsx-runtime.d.ts

@@ -0,0 +1,32 @@
+import type { JsxRenderable } from './jsx.js';
+export declare const Fragment: unique symbol;
+export declare function jsx(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxs(_: unknown, __?: unknown, ___?: unknown): JsxRenderable;
+export declare function jsxDEV(_: unknown, __?: unknown, ___?: unknown, ____?: boolean, _____?: unknown, ______?: unknown): JsxRenderable;
+type DataAttributes = {
+    [K in `data-${string}`]?: string | number | boolean | null | undefined;
+};
+type AriaAttributes = {
+    [K in `aria-${string}`]?: string | number | boolean | null | undefined;
+};
+type EventHandlers<T extends EventTarget> = {
+    [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<string & K>}`]?: (event: GlobalEventHandlersEventMap[K]) => void;
+};
+type ElementProps<Tag extends keyof HTMLElementTagNameMap> = Partial<HTMLElementTagNameMap[Tag]> & EventHandlers<HTMLElementTagNameMap[Tag]> & DataAttributes & AriaAttributes & {
+    class?: string;
+    className?: string;
+    style?: string | Record<string, string | number>;
+    ref?: ((value: HTMLElementTagNameMap[Tag]) => void) | {
+        current: HTMLElementTagNameMap[Tag] | null;
+    };
+    children?: JsxRenderable | JsxRenderable[];
+};
+declare global {
+    namespace JSX {
+        type Element = JsxRenderable;
+        type IntrinsicElements = {
+            [Tag in keyof HTMLElementTagNameMap]: ElementProps<Tag>;
+        };
+    }
+}
+export {};

package/dist/jsx-runtime.js

@@ -0,0 +1,16 @@
+const runtimeModuleId = '@knighted/jsx/jsx-runtime';
+const fragmentSymbolDescription = `${runtimeModuleId}::Fragment`;
+const runtimeNotAvailable = () => {
+    throw new Error(`The automatic JSX runtime is only published for TypeScript diagnostics. ` +
+        `Render DOM nodes through the jsx tagged template exported by @knighted/jsx instead.`);
+};
+export const Fragment = Symbol.for(fragmentSymbolDescription);
+export function jsx(_, __, ___) {
+    return runtimeNotAvailable();
+}
+export function jsxs(_, __, ___) {
+    return runtimeNotAvailable();
+}
+export function jsxDEV(_, __, ___, ____, _____, ______) {
+    return runtimeNotAvailable();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
     "jsx runtime",
@@ -26,6 +26,16 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js",
+      "default": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js",
+      "default": "./dist/jsx-runtime.js"
+    },
     "./lite": {
       "types": "./dist/index.d.ts",
       "import": "./dist/lite/index.js",