@knighted/jsx 1.2.1 → 1.3.1

package/README.md

@@ -20,7 +20,9 @@ A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-p
 - [Node / SSR usage](#node--ssr-usage)
 - [Next.js integration](#nextjs-integration)
 - [Browser usage](#browser-usage)
+- [Component testing](docs/testing.md)
 - [Testing & demos](#testing)
+- [CLI setup](docs/cli.md)
 
 ## Installation
 
@@ -34,12 +36,14 @@ npm install @knighted/jsx
 > [!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.
 
-The parser automatically uses native bindings when it runs in Node.js. To enable the WASM binding for browser builds you also need the `@oxc-parser/binding-wasm32-wasi` package. Because npm enforces the `cpu: ["wasm32"]` flag you must opt into the install explicitly:
+The parser automatically uses native bindings when it runs in Node.js. To enable the WASM binding for browser builds you also need the `@oxc-parser/binding-wasm32-wasi` package. The quickest path is:
 
 ```sh
-npm_config_ignore_platform=true npm install @oxc-parser/binding-wasm32-wasi
+npx @knighted/jsx init
 ```
 
+See [docs/cli.md](docs/cli.md) for flags, dry runs, and package-manager overrides. If you prefer manual install, run `npm_config_ignore_platform=true npm install @oxc-parser/binding-wasm32-wasi`.
+
 > [!TIP]
 > Public CDNs such as `esm.sh` or `jsdelivr` already publish bundles that include the WASM binding, so you can import this package directly from those endpoints in `<script type="module">` blocks without any extra setup.
 
@@ -334,6 +338,10 @@ Each lite subpath ships the same API as its standard counterpart but is pre-mini
 
 ## 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

package/dist/cjs/cli/init.cjs

@@ -0,0 +1,259 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.detectPackageManager = detectPackageManager;
+exports.ensurePackageJson = ensurePackageJson;
+exports.runNpmPack = runNpmPack;
+exports.parsePackageName = parsePackageName;
+exports.installBinding = installBinding;
+exports.installRuntimeDeps = installRuntimeDeps;
+exports.isDependencyInstalled = isDependencyInstalled;
+exports.persistBindingSpec = persistBindingSpec;
+exports.verifyBinding = verifyBinding;
+exports.promptYesNo = promptYesNo;
+exports.maybeHandleConfigPrompt = maybeHandleConfigPrompt;
+exports.main = main;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = __importDefault(require("node:readline/promises"));
+const node_module_1 = require("node:module");
+const node_url_1 = require("node:url");
+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'];
+function parseArgs(argv) {
+    const options = {
+        cwd: process.cwd(),
+        dryRun: false,
+        verbose: false,
+        force: false,
+        skipConfig: true,
+        wasmPackage: DEFAULT_BINDING_SPEC,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--dry-run') {
+            options.dryRun = true;
+        }
+        else if (arg === '--verbose') {
+            options.verbose = true;
+        }
+        else if (arg === '--force' || arg === '--yes') {
+            options.force = true;
+        }
+        else if (arg === '--skip-config') {
+            options.skipConfig = true;
+        }
+        else if (arg === '--config') {
+            options.skipConfig = false;
+        }
+        else if (arg === '--package-manager' || arg === '--pm') {
+            const pm = argv[i + 1];
+            if (!pm)
+                throw new Error('Missing value for --package-manager');
+            if (!SUPPORTED_PACKAGE_MANAGERS.includes(pm)) {
+                throw new Error(`Unsupported package manager: ${pm}`);
+            }
+            options.packageManager = pm;
+            i += 1;
+        }
+        else if (arg === '--wasm-package') {
+            const pkg = argv[i + 1];
+            if (!pkg)
+                throw new Error('Missing value for --wasm-package');
+            options.wasmPackage = pkg;
+            i += 1;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+    }
+    return options;
+}
+function printHelp() {
+    console.log(`\nUsage: npx @knighted/jsx init [options]\n\nOptions:\n  --package-manager, --pm <name>  Choose npm | pnpm | yarn | bun\n  --wasm-package <spec>           Override binding package spec\n  --config                        Prompt to help with loader config\n  --skip-config                   Skip any loader config prompts (default)\n  --dry-run                       Print actions without executing\n  --force, --yes                  Assume yes for prompts\n  --verbose                       Log extra detail\n  -h, --help                      Show this help message\n`);
+}
+function log(message) {
+    console.log(message);
+}
+function logVerbose(message, verbose) {
+    if (verbose)
+        console.log(message);
+}
+function detectPackageManager(cwd, explicit) {
+    if (explicit)
+        return explicit;
+    const ua = process.env.npm_config_user_agent ?? '';
+    if (ua.startsWith('pnpm'))
+        return 'pnpm';
+    if (ua.startsWith('yarn'))
+        return 'yarn';
+    if (ua.startsWith('bun'))
+        return 'bun';
+    const lookups = {
+        pnpm: 'pnpm-lock.yaml',
+        yarn: 'yarn.lock',
+        bun: 'bun.lockb',
+        npm: 'package-lock.json',
+    };
+    for (const [pm, lockfile] of Object.entries(lookups)) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(cwd, lockfile)))
+            return pm;
+    }
+    return 'npm';
+}
+function ensurePackageJson(cwd) {
+    const pkgPath = node_path_1.default.join(cwd, 'package.json');
+    if (!node_fs_1.default.existsSync(pkgPath)) {
+        throw new Error('No package.json found. Run this inside a project with package.json.');
+    }
+}
+function runNpmPack(spec, cwd, dryRun, verbose) {
+    logVerbose(`> npm pack ${spec}`, verbose);
+    if (dryRun)
+        return `${spec.replace(/\W+/g, '_')}.tgz`;
+    const output = (0, node_child_process_1.execFileSync)('npm', ['pack', spec], {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'inherit'],
+    }).trim();
+    const lines = output.split('\n').filter(Boolean);
+    return lines[lines.length - 1];
+}
+function parsePackageName(spec) {
+    const match = spec.match(/^(@?[^@\s]+\/[^@\s]+|@?[^@\s]+)(?:@(.+))?$/);
+    if (!match)
+        return { name: spec, version: undefined };
+    const [, name, version] = match;
+    return { name, version };
+}
+async function installBinding(spec, cwd, dryRun, verbose) {
+    const { name, version } = parsePackageName(spec);
+    const tarballName = runNpmPack(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}`);
+    if (!dryRun) {
+        node_fs_1.default.rmSync(targetDir, { recursive: true, force: true });
+        node_fs_1.default.mkdirSync(targetDir, { recursive: true });
+        await (0, tar_1.extract)({ file: tarballPath, cwd: targetDir, strip: 1 });
+        node_fs_1.default.rmSync(tarballPath, { force: true });
+    }
+    return { targetDir, tarballPath: dryRun ? undefined : tarballPath, name, version };
+}
+function installRuntimeDeps(pm, deps, cwd, dryRun, verbose) {
+    const missing = deps.filter(dep => !isDependencyInstalled(dep, cwd));
+    if (missing.length === 0) {
+        log('> Runtime dependencies already present; skipping install');
+        return [];
+    }
+    const commands = {
+        npm: ['npm', ['install', ...missing, '--save']],
+        pnpm: ['pnpm', ['add', ...missing]],
+        yarn: ['yarn', ['add', ...missing]],
+        bun: ['bun', ['add', ...missing]],
+    };
+    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' });
+        if (result.status !== 0) {
+            throw new Error(`Failed to install runtime dependencies with ${pm}`);
+        }
+    }
+    return missing;
+}
+function isDependencyInstalled(dep, cwd) {
+    try {
+        const requireFromCwd = (0, node_module_1.createRequire)(node_path_1.default.join(cwd, 'package.json'));
+        requireFromCwd.resolve(dep);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function persistBindingSpec(cwd, name, version, dryRun, verbose) {
+    if (!version) {
+        logVerbose('> Skipping package.json update (no version parsed)', verbose);
+        return;
+    }
+    const pkgPath = node_path_1.default.join(cwd, 'package.json');
+    const pkgRaw = node_fs_1.default.readFileSync(pkgPath, 'utf8');
+    const pkgJson = JSON.parse(pkgRaw);
+    pkgJson.optionalDependencies = pkgJson.optionalDependencies ?? {};
+    pkgJson.optionalDependencies[name] = version;
+    log(`> Recording optionalDependency ${name}@${version}`);
+    if (!dryRun) {
+        node_fs_1.default.writeFileSync(pkgPath, `${JSON.stringify(pkgJson, null, 2)}\n`, 'utf8');
+    }
+}
+async function verifyBinding(name, cwd, verbose) {
+    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);
+    if (!imported) {
+        throw new Error(`Imported ${name} is empty; verification failed`);
+    }
+    return resolved;
+}
+async function promptYesNo(prompt, defaultValue, force) {
+    if (!process.stdin.isTTY)
+        return defaultValue;
+    if (force)
+        return true;
+    const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = await rl.question(`${prompt} ${suffix} `);
+    await rl.close();
+    if (!answer.trim())
+        return defaultValue;
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}
+async function maybeHandleConfigPrompt(skipConfig, force) {
+    if (skipConfig) {
+        log('> Skipping loader config (default). Re-run with --config to opt in.');
+        return;
+    }
+    const wantsHelp = await promptYesNo('Do you want help adding loader configuration now?', false, force);
+    if (!wantsHelp) {
+        log('> Skipping loader config per your choice.');
+        return;
+    }
+    log('> Loader assistance is interactive and not applied automatically yet. See docs at docs/cli.md for next steps.');
+}
+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);
+    let resolvedPath;
+    if (!options.dryRun) {
+        resolvedPath = await verifyBinding(binding.name, options.cwd, options.verbose);
+        log(`> 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)'}`);
+    if (resolvedPath)
+        log(`- Verified import: ${resolvedPath}`);
+}
+if (process.env.KNIGHTED_JSX_CLI_TEST !== '1') {
+    main().catch(error => {
+        console.error('Failed to set up WASM binding:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
+}

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

@@ -0,0 +1,36 @@
+declare const SUPPORTED_PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
+type PackageManager = (typeof SUPPORTED_PACKAGE_MANAGERS)[number];
+type CliOptions = {
+    cwd: string;
+    dryRun: boolean;
+    verbose: boolean;
+    force: boolean;
+    skipConfig: boolean;
+    packageManager?: PackageManager;
+    wasmPackage: string;
+};
+declare function parseArgs(argv: string[]): CliOptions;
+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 parsePackageName(spec: string): {
+    name: string;
+    version: undefined;
+} | {
+    name: string;
+    version: string;
+};
+declare function installBinding(spec: string, cwd: string, dryRun: boolean, verbose: boolean): 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 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>;
+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>;
+export { parseArgs, detectPackageManager, ensurePackageJson, runNpmPack, parsePackageName, installBinding, installRuntimeDeps, isDependencyInstalled, persistBindingSpec, verifyBinding, promptYesNo, maybeHandleConfigPrompt, main, };

package/dist/cli/init.d.ts

@@ -0,0 +1,36 @@
+declare const SUPPORTED_PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
+type PackageManager = (typeof SUPPORTED_PACKAGE_MANAGERS)[number];
+type CliOptions = {
+    cwd: string;
+    dryRun: boolean;
+    verbose: boolean;
+    force: boolean;
+    skipConfig: boolean;
+    packageManager?: PackageManager;
+    wasmPackage: string;
+};
+declare function parseArgs(argv: string[]): CliOptions;
+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 parsePackageName(spec: string): {
+    name: string;
+    version: undefined;
+} | {
+    name: string;
+    version: string;
+};
+declare function installBinding(spec: string, cwd: string, dryRun: boolean, verbose: boolean): 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 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>;
+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>;
+export { parseArgs, detectPackageManager, ensurePackageJson, runNpmPack, parsePackageName, installBinding, installRuntimeDeps, isDependencyInstalled, persistBindingSpec, verifyBinding, promptYesNo, maybeHandleConfigPrompt, main, };

package/dist/cli/init.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+import { spawnSync, execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline/promises';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+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"];
+function parseArgs(argv) {
+  const options = {
+    cwd: process.cwd(),
+    dryRun: false,
+    verbose: false,
+    force: false,
+    skipConfig: true,
+    wasmPackage: DEFAULT_BINDING_SPEC
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--verbose") {
+      options.verbose = true;
+    } else if (arg === "--force" || arg === "--yes") {
+      options.force = true;
+    } else if (arg === "--skip-config") {
+      options.skipConfig = true;
+    } else if (arg === "--config") {
+      options.skipConfig = false;
+    } else if (arg === "--package-manager" || arg === "--pm") {
+      const pm = argv[i + 1];
+      if (!pm) throw new Error("Missing value for --package-manager");
+      if (!SUPPORTED_PACKAGE_MANAGERS.includes(pm)) {
+        throw new Error(`Unsupported package manager: ${pm}`);
+      }
+      options.packageManager = pm;
+      i += 1;
+    } else if (arg === "--wasm-package") {
+      const pkg = argv[i + 1];
+      if (!pkg) throw new Error("Missing value for --wasm-package");
+      options.wasmPackage = pkg;
+      i += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  return options;
+}
+function printHelp() {
+  console.log(
+    `
+Usage: npx @knighted/jsx init [options]
+
+Options:
+  --package-manager, --pm <name>  Choose npm | pnpm | yarn | bun
+  --wasm-package <spec>           Override binding package spec
+  --config                        Prompt to help with loader config
+  --skip-config                   Skip any loader config prompts (default)
+  --dry-run                       Print actions without executing
+  --force, --yes                  Assume yes for prompts
+  --verbose                       Log extra detail
+  -h, --help                      Show this help message
+`
+  );
+}
+function log(message) {
+  console.log(message);
+}
+function logVerbose(message, verbose) {
+  if (verbose) console.log(message);
+}
+function detectPackageManager(cwd, explicit) {
+  if (explicit) return explicit;
+  const ua = process.env.npm_config_user_agent ?? "";
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("bun")) return "bun";
+  const lookups = {
+    pnpm: "pnpm-lock.yaml",
+    yarn: "yarn.lock",
+    bun: "bun.lockb",
+    npm: "package-lock.json"
+  };
+  for (const [pm, lockfile] of Object.entries(lookups)) {
+    if (fs.existsSync(path.join(cwd, lockfile))) return pm;
+  }
+  return "npm";
+}
+function ensurePackageJson(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    throw new Error("No package.json found. Run this inside a project with package.json.");
+  }
+}
+function runNpmPack(spec, cwd, dryRun, verbose) {
+  logVerbose(`> npm pack ${spec}`, verbose);
+  if (dryRun) return `${spec.replace(/\W+/g, "_")}.tgz`;
+  const output = execFileSync("npm", ["pack", spec], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"]
+  }).trim();
+  const lines = output.split("\n").filter(Boolean);
+  return lines[lines.length - 1];
+}
+function parsePackageName(spec) {
+  const match = spec.match(/^(@?[^@\s]+\/[^@\s]+|@?[^@\s]+)(?:@(.+))?$/);
+  if (!match) return { name: spec, version: void 0 };
+  const [, name, version] = match;
+  return { name, version };
+}
+async function installBinding(spec, cwd, dryRun, verbose) {
+  const { name, version } = parsePackageName(spec);
+  const tarballName = runNpmPack(spec, cwd, dryRun, verbose);
+  const tarballPath = path.resolve(cwd, tarballName);
+  const targetDir = path.resolve(cwd, "node_modules", ...name.split("/"));
+  log(`> Installing ${spec} into ${targetDir}`);
+  if (!dryRun) {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    fs.mkdirSync(targetDir, { recursive: true });
+    await extract({ file: tarballPath, cwd: targetDir, strip: 1 });
+    fs.rmSync(tarballPath, { force: true });
+  }
+  return { targetDir, tarballPath: dryRun ? void 0 : tarballPath, name, version };
+}
+function installRuntimeDeps(pm, deps, cwd, dryRun, verbose) {
+  const missing = deps.filter((dep) => !isDependencyInstalled(dep, cwd));
+  if (missing.length === 0) {
+    log("> Runtime dependencies already present; skipping install");
+    return [];
+  }
+  const commands = {
+    npm: ["npm", ["install", ...missing, "--save"]],
+    pnpm: ["pnpm", ["add", ...missing]],
+    yarn: ["yarn", ["add", ...missing]],
+    bun: ["bun", ["add", ...missing]]
+  };
+  const [command, args] = commands[pm];
+  logVerbose(`> ${command} ${args.join(" ")}`, verbose);
+  if (!dryRun) {
+    const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+    if (result.status !== 0) {
+      throw new Error(`Failed to install runtime dependencies with ${pm}`);
+    }
+  }
+  return missing;
+}
+function isDependencyInstalled(dep, cwd) {
+  try {
+    const requireFromCwd = createRequire(path.join(cwd, "package.json"));
+    requireFromCwd.resolve(dep);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function persistBindingSpec(cwd, name, version, dryRun, verbose) {
+  if (!version) {
+    logVerbose("> Skipping package.json update (no version parsed)", verbose);
+    return;
+  }
+  const pkgPath = path.join(cwd, "package.json");
+  const pkgRaw = fs.readFileSync(pkgPath, "utf8");
+  const pkgJson = JSON.parse(pkgRaw);
+  pkgJson.optionalDependencies = pkgJson.optionalDependencies ?? {};
+  pkgJson.optionalDependencies[name] = version;
+  log(`> Recording optionalDependency ${name}@${version}`);
+  if (!dryRun) {
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkgJson, null, 2)}
+`, "utf8");
+  }
+}
+async function verifyBinding(name, cwd, verbose) {
+  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);
+  if (!imported) {
+    throw new Error(`Imported ${name} is empty; verification failed`);
+  }
+  return resolved;
+}
+async function promptYesNo(prompt, defaultValue, force) {
+  if (!process.stdin.isTTY) return defaultValue;
+  if (force) return true;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultValue ? "[Y/n]" : "[y/N]";
+  const answer = await rl.question(`${prompt} ${suffix} `);
+  await rl.close();
+  if (!answer.trim()) return defaultValue;
+  const normalized = answer.trim().toLowerCase();
+  return normalized === "y" || normalized === "yes";
+}
+async function maybeHandleConfigPrompt(skipConfig, force) {
+  if (skipConfig) {
+    log("> Skipping loader config (default). Re-run with --config to opt in.");
+    return;
+  }
+  const wantsHelp = await promptYesNo(
+    "Do you want help adding loader configuration now?",
+    false,
+    force
+  );
+  if (!wantsHelp) {
+    log("> Skipping loader config per your choice.");
+    return;
+  }
+  log(
+    "> Loader assistance is interactive and not applied automatically yet. See docs at docs/cli.md for next steps."
+  );
+}
+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
+  );
+  let resolvedPath;
+  if (!options.dryRun) {
+    resolvedPath = await verifyBinding(binding.name, options.cwd, options.verbose);
+    log(`> 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)"}`
+  );
+  if (resolvedPath) log(`- Verified import: ${resolvedPath}`);
+}
+if (process.env.KNIGHTED_JSX_CLI_TEST !== "1") {
+  main().catch((error) => {
+    console.error(
+      "Failed to set up WASM binding:",
+      error instanceof Error ? error.message : error
+    );
+    process.exitCode = 1;
+  });
+}
+
+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.2.1",
+  "version": "1.3.1",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
     "jsx runtime",
@@ -17,6 +17,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "jsx": "./dist/cli/init.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -65,11 +68,11 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=22.3.0"
+    "node": ">=22.17.0"
   },
   "engineStrict": true,
   "scripts": {
-    "build": "duel && npm run build:lite",
+    "build": "duel && npm run build:lite && npm run build:cli",
     "prepare": "husky",
     "precheck-types": "npm run build",
     "check-types": "npm run check-types:lib && npm run check-types:demo",
@@ -78,8 +81,8 @@
     "lint": "eslint src test",
     "prettier": "prettier -w .",
     "prettier:check": "prettier --check .",
-    "test": "vitest run --coverage",
-    "test:watch": "vitest",
+    "test": "KNIGHTED_JSX_CLI_TEST=1 vitest run --coverage",
+    "test:watch": "KNIGHTED_JSX_CLI_TEST=1 vitest",
     "test:e2e": "npm run build && npm run setup:wasm && npm run build:fixture && playwright test",
     "build:fixture": "node scripts/build-rspack-fixture.mjs",
     "demo:node-ssr": "node test/fixtures/node-ssr/render.mjs",
@@ -87,6 +90,7 @@
     "build:demo": "vite build --config vite.config.ts",
     "preview": "vite preview --config vite.config.ts",
     "build:lite": "tsup --config tsup.config.ts",
+    "build:cli": "tsup --config tsup.cli.config.ts",
     "setup:wasm": "node scripts/setup-wasm.mjs",
     "prepack": "npm run build"
   },
@@ -113,7 +117,6 @@
     "prettier": "^3.7.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "tar": "^7.4.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.0",
@@ -122,7 +125,8 @@
   },
   "dependencies": {
     "magic-string": "^0.30.21",
-    "oxc-parser": "^0.99.0"
+    "oxc-parser": "^0.99.0",
+    "tar": "^7.4.3"
   },
   "peerDependencies": {
     "jsdom": "*",