@knighted/jsx 1.2.0-rc.1 → 1.2.0-rc.3

package/README.md

@@ -56,7 +56,7 @@ const handleClick = () => {
 
 const button = jsx`
   <button className={${`counter-${count}`}} onClick={${handleClick}}>
-    Count is {${count}}
+    Count is ${count}
   </button>
 `
 
@@ -78,7 +78,7 @@ const App = () => {
   return reactJsx`
     <section className="react-demo">
       <h2>Hello from React</h2>
-      <p>Count is {${count}}</p>
+      <p>Count is ${count}</p>
       <button onClick={${() => setCount(value => value + 1)}}>
         Increment
       </button>
@@ -127,14 +127,14 @@ npm run setup:wasm
 npm run build:fixture
 ```
 
-Then point a static server at the fixture root (which serves `index.html` and the bundled `dist/bundle.js`) to see it in a browser:
+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 the Lit + React demo.
+Visit `http://localhost:4173` (or whichever port you pick) to interact with both the Lit + React hybrid demo and the React-mode bundle.
 
 ## Node / SSR usage
 
@@ -147,12 +147,12 @@ import { renderToString } from 'react-dom/server'
 
 const Badge = ({ label }: { label: string }) =>
   reactJsx`
-    <button type="button">React says: {${label}}</button>
+    <button type="button">React says: ${label}</button>
   `
 
 const reactMarkup = renderToString(
   reactJsx`
-    <${Badge} label={${'Server-only'}} />
+    <${Badge} label="Server-only" />
   `,
 )
 
@@ -250,7 +250,7 @@ Build the fixture locally with `npx next build test/fixtures/next-app` (or run `
 
 ### Interpolations
 
-- All dynamic values are provided through standard template literal expressions (`${...}`). Wrap them in JSX braces to keep the syntax valid: `className={${value}}`, `{${items}}`, etc.
+- All dynamic values are provided through standard template literal expressions (`${...}`) and map to JSX exactly where they appear. Use JSX braces anywhere the syntax normally requires them (`className={${value}}`, spreads, etc.), but plain text children can interpolate directly, e.g. `Count is ${value}`.
 - 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.
 
@@ -266,10 +266,12 @@ const Button = ({ children, variant = 'primary' }) => {
   return el
 }
 
+const label = 'Tap me'
+
 const view = jsx`
   <section>
-    <${Button} variant={${'ghost'}}>
-      {${'Tap me'}}
+    <${Button} variant="ghost">
+      ${label}
     </${Button}>
   </section>
 `
@@ -336,6 +338,15 @@ 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`).
+
 ## 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):
@@ -357,19 +368,6 @@ For a zero-build verification of the lite bundle, open `examples/esm-demo-lite.h
 - JSX identifiers are resolved at runtime through template interpolations; you cannot reference closures directly inside the template without using `${...}`.
 - Promises/async components are not supported.
 
-## Performance notes vs `htm`
-
-[`htm`](https://github.com/developit/htm) popularized tagged template literals for view rendering by tokenizing the template strings on the fly and calling a user-provided hyperscript function. This library takes a different approach: every invocation runs the native `oxc-parser` (compiled to WebAssembly) to build a real JSX AST before constructing DOM nodes.
-
-Tradeoffs to keep in mind:
-
-- **Parser vs tokenizer** – `htm` performs lightweight string tokenization, while `@knighted/jsx` pays a higher one-time parse cost but gains the full JSX grammar (fragments, spread children, nested namespaces) without heuristics. For large or deeply nested templates the WASM-backed parser is typically faster and more accurate than string slicing.
-- **DOM-first rendering** – this runtime builds DOM nodes directly, so the cost after parsing is mostly attribute assignment and child insertion. `htm` usually feeds a virtual DOM/hyperscript factory (e.g., Preact’s `h`), which may add an extra abstraction layer before hitting the DOM.
-- **Bundle size** – including the parser and WASM binding is heavier than `htm`’s ~1 kB tokenizer. If you just need hyperscript sugar, `htm` stays leaner; if you value real JSX semantics without a build step, the extra kilobytes buy you correctness and speed on complex trees.
-  - **Actual size** – as of `v1.2.0-rc.1` the default `dist/jsx.js` bundle is ~9.0 kB raw / ~2.3 kB min+gzip, while the `@knighted/jsx/lite` entry stays ~5.7 kB raw / ~2.5 kB min+gzip. `htm` weighs in at roughly 0.7 kB min+gzip, so the lite entry narrows the gap to ~1.8 kB for production payloads.
-
-In short, `@knighted/jsx` trades a slightly larger runtime for the ability to parse genuine JSX with native performance, whereas `htm` favors minimal footprint and hyperscript integration. Pick the tool that aligns with your rendering stack and performance envelope.
-
 ## License
 
 MIT © Knighted Code Monkey

package/dist/cjs/loader/jsx.cjs

@@ -6,6 +6,168 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = jsxLoader;
 const magic_string_1 = __importDefault(require("magic-string"));
 const oxc_parser_1 = require("oxc-parser");
+const createPlaceholderMap = (placeholders) => new Map(placeholders.map(entry => [entry.marker, entry.code]));
+class ReactTemplateBuilder {
+    placeholderMap;
+    constructor(placeholderSource) {
+        this.placeholderMap = createPlaceholderMap(placeholderSource);
+    }
+    compile(node) {
+        return this.compileNode(node);
+    }
+    compileNode(node) {
+        if (node.type === 'JSXFragment') {
+            const children = this.compileChildren(node.children);
+            return this.buildCreateElement('React.Fragment', 'null', children);
+        }
+        const opening = node.openingElement;
+        const tagExpr = this.compileTagName(opening.name);
+        const propsExpr = this.compileProps(opening.attributes);
+        const children = this.compileChildren(node.children);
+        return this.buildCreateElement(tagExpr, propsExpr, children);
+    }
+    compileChildren(children) {
+        const compiled = [];
+        children.forEach(child => {
+            switch (child.type) {
+                case 'JSXText': {
+                    const text = normalizeJsxTextValue(child.value);
+                    if (text) {
+                        compiled.push(JSON.stringify(text));
+                    }
+                    break;
+                }
+                case 'JSXExpressionContainer': {
+                    if (child.expression.type === 'JSXEmptyExpression') {
+                        break;
+                    }
+                    compiled.push(this.compileExpression(child.expression));
+                    break;
+                }
+                case 'JSXSpreadChild': {
+                    compiled.push(this.compileExpression(child.expression));
+                    break;
+                }
+                case 'JSXElement':
+                case 'JSXFragment': {
+                    compiled.push(this.compileNode(child));
+                    break;
+                }
+            }
+        });
+        return compiled;
+    }
+    compileProps(attributes) {
+        const segments = [];
+        let staticEntries = [];
+        const flushStatics = () => {
+            if (!staticEntries.length) {
+                return;
+            }
+            segments.push(`{ ${staticEntries.join(', ')} }`);
+            staticEntries = [];
+        };
+        attributes.forEach(attribute => {
+            if (attribute.type === 'JSXSpreadAttribute') {
+                flushStatics();
+                segments.push(this.compileExpression(attribute.argument));
+                return;
+            }
+            const name = this.compileAttributeName(attribute.name);
+            let value;
+            if (!attribute.value) {
+                value = 'true';
+            }
+            else if (attribute.value.type === 'Literal') {
+                value = JSON.stringify(attribute.value.value);
+            }
+            else if (attribute.value.type === 'JSXExpressionContainer') {
+                if (attribute.value.expression.type === 'JSXEmptyExpression') {
+                    return;
+                }
+                value = this.compileExpression(attribute.value.expression);
+            }
+            else {
+                value = 'undefined';
+            }
+            staticEntries.push(`${JSON.stringify(name)}: ${value}`);
+        });
+        flushStatics();
+        if (!segments.length) {
+            return 'null';
+        }
+        if (segments.length === 1) {
+            return segments[0];
+        }
+        return `__jsxReactMergeProps(${segments.join(', ')})`;
+    }
+    compileAttributeName(name) {
+        switch (name.type) {
+            case 'JSXIdentifier':
+                return name.name;
+            case 'JSXNamespacedName':
+                return `${name.namespace.name}:${name.name.name}`;
+            case 'JSXMemberExpression':
+                return `${this.compileAttributeName(name.object)}.${name.property.name}`;
+            default:
+                /* c8 ignore next */
+                return '';
+        }
+    }
+    compileTagName(name) {
+        if (!name) {
+            /* c8 ignore next */
+            throw new Error('[jsx-loader] Encountered JSX element without a tag name.');
+        }
+        if (name.type === 'JSXIdentifier') {
+            if (isLoaderPlaceholderIdentifier(name) && name.name) {
+                const resolved = this.placeholderMap.get(name.name);
+                if (!resolved) {
+                    /* c8 ignore next 3 */
+                    throw new Error('[jsx-loader] Unable to resolve placeholder for tag expression.');
+                }
+                return resolved;
+            }
+            if (/^[A-Z]/.test(name.name)) {
+                return name.name;
+            }
+            return JSON.stringify(name.name);
+        }
+        if (name.type === 'JSXMemberExpression') {
+            const object = this.compileTagName(name.object);
+            return `${object}.${name.property.name}`;
+        }
+        if (name.type === 'JSXNamespacedName') {
+            return JSON.stringify(`${name.namespace.name}:${name.name.name}`);
+        }
+        /* c8 ignore next */
+        throw new Error('[jsx-loader] Unsupported tag expression in react mode.');
+    }
+    compileExpression(node) {
+        if (node.type === 'JSXElement' || node.type === 'JSXFragment') {
+            return this.compileNode(node);
+        }
+        if (node.type === 'Identifier') {
+            const resolved = this.placeholderMap.get(node.name);
+            if (resolved) {
+                return resolved;
+            }
+            return node.name;
+        }
+        if ('range' in node && Array.isArray(node.range)) {
+            throw new Error('[jsx-loader] Unable to inline complex expressions in react mode.');
+        }
+        /* c8 ignore next */
+        throw new Error('[jsx-loader] Unable to compile expression for react mode.');
+    }
+    buildCreateElement(type, props, children) {
+        const args = [type, props];
+        if (children.length) {
+            args.push(children.join(', '));
+        }
+        return `__jsxReact(${args.join(', ')})`;
+    }
+}
 const stripTrailingWhitespace = (value) => value.replace(/\s+$/g, '');
 const stripLeadingWhitespace = (value) => value.replace(/^\s+/g, '');
 const getTemplateExpressionContext = (left, right) => {
@@ -49,6 +211,24 @@ const TEMPLATE_PARSER_OPTIONS = {
     preserveParens: true,
 };
 const DEFAULT_TAGS = ['jsx', 'reactJsx'];
+const DEFAULT_MODE = 'runtime';
+const HELPER_SNIPPETS = {
+    react: `const __jsxReactMergeProps = (...sources) => Object.assign({}, ...sources)
+const __jsxReact = (type, props, ...children) => React.createElement(type, props, ...children)
+`,
+};
+const parseLoaderMode = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    switch (value) {
+        case 'runtime':
+        case 'react':
+            return value;
+        default:
+            return null;
+    }
+};
 const escapeTemplateChunk = (chunk) => chunk.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\${/g, '\\${');
 const formatParserError = (error) => {
     let message = `[jsx-loader] ${error.message}`;
@@ -87,10 +267,12 @@ const walkAst = (node, visitor) => {
 const shouldInterpolateName = (name) => /^[A-Z]/.test(name.name);
 const addSlot = (slots, source, range) => {
     if (!range) {
+        /* c8 ignore next */
         return;
     }
     const [start, end] = range;
     if (start === end) {
+        /* c8 ignore next */
         return;
     }
     slots.push({
@@ -118,6 +300,7 @@ const collectSlots = (program, source) => {
                 break;
             }
             default:
+                /* c8 ignore next */
                 break;
         }
     };
@@ -170,6 +353,7 @@ const renderTemplateWithSlots = (source, slots) => {
     let output = '';
     slots.forEach(slot => {
         if (slot.start < cursor) {
+            /* c8 ignore next */
             throw new Error('Overlapping JSX expressions detected inside template literal.');
         }
         output += escapeTemplateChunk(source.slice(cursor, slot.start));
@@ -197,6 +381,22 @@ const getTaggedTemplateName = (node) => {
     }
     return tagNode.name;
 };
+const extractJsxRoot = (program) => {
+    for (const statement of program.body) {
+        if (statement.type === 'ExpressionStatement') {
+            const expression = statement.expression;
+            if (expression.type === 'JSXElement' || expression.type === 'JSXFragment') {
+                return expression;
+            }
+        }
+    }
+    throw new Error('[jsx-loader] Expected the template to contain a single JSX root node.');
+};
+const normalizeJsxTextValue = (value) => {
+    const collapsed = value.replace(/\r/g, '').replace(/\n\s+/g, ' ');
+    const trimmed = collapsed.trim();
+    return trimmed.length > 0 ? trimmed : '';
+};
 const TAG_PLACEHOLDER_PREFIX = '__JSX_LOADER_TAG_EXPR_';
 const buildTemplateSource = (quasis, expressions, source, tag) => {
     const placeholderMap = new Map();
@@ -223,6 +423,7 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
     quasis.forEach((quasi, index) => {
         let chunk = quasi.value.cooked;
         if (typeof chunk !== 'string') {
+            /* c8 ignore next */
             chunk = quasi.value.raw ?? '';
         }
         if (trimStartNext > 0) {
@@ -237,6 +438,7 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
         const start = expression.start ?? null;
         const end = expression.end ?? null;
         if (start === null || end === null) {
+            /* c8 ignore next */
             throw new Error('Unable to read template expression source range.');
         }
         const nextChunk = quasis[index + 1];
@@ -293,8 +495,20 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
 const restoreTemplatePlaceholders = (code, placeholders) => placeholders.reduce((result, placeholder) => {
     return result.split(placeholder.marker).join(`\${${placeholder.code}}`);
 }, code);
+const compileReactTemplate = (templateSource, placeholders, resourcePath) => {
+    const parsed = (0, oxc_parser_1.parseSync)(`${resourcePath}?jsx-react-template`, templateSource, TEMPLATE_PARSER_OPTIONS);
+    if (parsed.errors.length > 0) {
+        throw new Error(formatParserError(parsed.errors[0]));
+    }
+    const root = extractJsxRoot(parsed.program);
+    const builder = new ReactTemplateBuilder(placeholders);
+    return builder.compile(root);
+};
 const isLoaderPlaceholderIdentifier = (node) => {
-    if (node?.type !== 'Identifier' || typeof node.name !== 'string') {
+    if (!node ||
+        (node.type !== 'Identifier' && node.type !== 'JSXIdentifier') ||
+        typeof node.name !== 'string') {
+        /* c8 ignore next */
         return false;
     }
     return (node.name.startsWith(TEMPLATE_EXPR_PLACEHOLDER_PREFIX) ||
@@ -313,28 +527,47 @@ const transformSource = (source, config) => {
         }
     });
     if (!taggedTemplates.length) {
-        return source;
+        return { code: source, helpers: [] };
     }
     const magic = new magic_string_1.default(source);
     let mutated = false;
+    const helperKinds = new Set();
     taggedTemplates
         .sort((a, b) => b.node.start - a.node.start)
         .forEach(entry => {
         const { node, tagName } = entry;
+        const mode = config.tagModes.get(tagName) ?? DEFAULT_MODE;
         const quasi = node.quasi;
         const templateSource = buildTemplateSource(quasi.quasis, quasi.expressions, source, tagName);
-        const { code, changed } = transformTemplateLiteral(templateSource.source, config.resourcePath);
-        const restored = restoreTemplatePlaceholders(code, templateSource.placeholders);
-        const templateChanged = changed || templateSource.mutated;
-        if (!templateChanged) {
+        if (mode === 'runtime') {
+            const { code, changed } = transformTemplateLiteral(templateSource.source, config.resourcePath);
+            const restored = restoreTemplatePlaceholders(code, templateSource.placeholders);
+            const templateChanged = changed || templateSource.mutated;
+            if (!templateChanged) {
+                return;
+            }
+            const tagSource = source.slice(node.tag.start, node.tag.end);
+            const replacement = `${tagSource}\`${restored}\``;
+            magic.overwrite(node.start, node.end, replacement);
+            mutated = true;
+            return;
+        }
+        if (mode === 'react') {
+            const compiled = compileReactTemplate(templateSource.source, templateSource.placeholders, config.resourcePath);
+            helperKinds.add('react');
+            magic.overwrite(node.start, node.end, compiled);
+            mutated = true;
             return;
         }
-        const tagSource = source.slice(node.tag.start, node.tag.end);
-        const replacement = `${tagSource}\`${restored}\``;
-        magic.overwrite(node.start, node.end, replacement);
-        mutated = true;
+        /* c8 ignore next */
+        throw new Error(`[jsx-loader] Transformation mode "${mode}" not implemented yet for tag "${tagName}".`);
     });
-    return mutated ? magic.toString() : source;
+    return {
+        code: mutated ? magic.toString() : source,
+        helpers: Array.from(helperKinds)
+            .map(kind => HELPER_SNIPPETS[kind])
+            .filter(Boolean),
+    };
 };
 function jsxLoader(input) {
     const callback = this.async();
@@ -349,13 +582,37 @@ function jsxLoader(input) {
             : legacyTag
                 ? [legacyTag]
                 : DEFAULT_TAGS;
-        const tags = Array.from(new Set(tagList));
+        const tagModes = new Map();
+        const configuredTagModes = options.tagModes && typeof options.tagModes === 'object'
+            ? options.tagModes
+            : undefined;
+        if (configuredTagModes) {
+            Object.entries(configuredTagModes).forEach(([tagName, mode]) => {
+                const parsed = parseLoaderMode(mode);
+                if (!parsed || typeof tagName !== 'string' || !tagName.length) {
+                    return;
+                }
+                tagModes.set(tagName, parsed);
+            });
+        }
+        const defaultMode = parseLoaderMode(options.mode) ?? DEFAULT_MODE;
+        const tags = Array.from(new Set([...tagList, ...tagModes.keys()]));
+        tags.forEach(tagName => {
+            if (!tagModes.has(tagName)) {
+                tagModes.set(tagName, defaultMode);
+            }
+        });
         const source = typeof input === 'string' ? input : input.toString('utf8');
-        const output = transformSource(source, {
+        const { code, helpers } = transformSource(source, {
             resourcePath: this.resourcePath,
             tags,
+            tagModes,
         });
-        callback(null, output);
+        if (helpers.length) {
+            callback(null, `${code}\n${helpers.join('\n')}`);
+            return;
+        }
+        callback(null, code);
     }
     catch (error) {
         callback(error);

package/dist/cjs/loader/jsx.d.cts

@@ -4,16 +4,26 @@ type LoaderContext<TOptions> = {
     async(): LoaderCallback;
     getOptions?: () => Partial<TOptions>;
 };
+type LoaderMode = 'runtime' | 'react';
 type LoaderOptions = {
     /**
      * Name of the tagged template function. Defaults to `jsx`.
      * Deprecated in favor of `tags`.
+     * @deprecated Use `tags` instead.
      */
     tag?: string;
     /**
      * List of tagged template function names to transform. Defaults to `['jsx', 'reactJsx']`.
      */
     tags?: string[];
+    /**
+     * Global transformation mode for every tag. Defaults to `runtime`.
+     */
+    mode?: LoaderMode;
+    /**
+     * Optional per-tag override of the transformation mode. Keys map to tag names.
+     */
+    tagModes?: Record<string, LoaderMode | undefined>;
 };
 export default function jsxLoader(this: LoaderContext<LoaderOptions>, input: string | Buffer): void;
 export {};

package/dist/loader/jsx.d.ts

@@ -4,16 +4,26 @@ type LoaderContext<TOptions> = {
     async(): LoaderCallback;
     getOptions?: () => Partial<TOptions>;
 };
+type LoaderMode = 'runtime' | 'react';
 type LoaderOptions = {
     /**
      * Name of the tagged template function. Defaults to `jsx`.
      * Deprecated in favor of `tags`.
+     * @deprecated Use `tags` instead.
      */
     tag?: string;
     /**
      * List of tagged template function names to transform. Defaults to `['jsx', 'reactJsx']`.
      */
     tags?: string[];
+    /**
+     * Global transformation mode for every tag. Defaults to `runtime`.
+     */
+    mode?: LoaderMode;
+    /**
+     * Optional per-tag override of the transformation mode. Keys map to tag names.
+     */
+    tagModes?: Record<string, LoaderMode | undefined>;
 };
 export default function jsxLoader(this: LoaderContext<LoaderOptions>, input: string | Buffer): void;
 export {};

package/dist/loader/jsx.js

@@ -1,5 +1,167 @@
 import MagicString from 'magic-string';
 import { parseSync } from 'oxc-parser';
+const createPlaceholderMap = (placeholders) => new Map(placeholders.map(entry => [entry.marker, entry.code]));
+class ReactTemplateBuilder {
+    placeholderMap;
+    constructor(placeholderSource) {
+        this.placeholderMap = createPlaceholderMap(placeholderSource);
+    }
+    compile(node) {
+        return this.compileNode(node);
+    }
+    compileNode(node) {
+        if (node.type === 'JSXFragment') {
+            const children = this.compileChildren(node.children);
+            return this.buildCreateElement('React.Fragment', 'null', children);
+        }
+        const opening = node.openingElement;
+        const tagExpr = this.compileTagName(opening.name);
+        const propsExpr = this.compileProps(opening.attributes);
+        const children = this.compileChildren(node.children);
+        return this.buildCreateElement(tagExpr, propsExpr, children);
+    }
+    compileChildren(children) {
+        const compiled = [];
+        children.forEach(child => {
+            switch (child.type) {
+                case 'JSXText': {
+                    const text = normalizeJsxTextValue(child.value);
+                    if (text) {
+                        compiled.push(JSON.stringify(text));
+                    }
+                    break;
+                }
+                case 'JSXExpressionContainer': {
+                    if (child.expression.type === 'JSXEmptyExpression') {
+                        break;
+                    }
+                    compiled.push(this.compileExpression(child.expression));
+                    break;
+                }
+                case 'JSXSpreadChild': {
+                    compiled.push(this.compileExpression(child.expression));
+                    break;
+                }
+                case 'JSXElement':
+                case 'JSXFragment': {
+                    compiled.push(this.compileNode(child));
+                    break;
+                }
+            }
+        });
+        return compiled;
+    }
+    compileProps(attributes) {
+        const segments = [];
+        let staticEntries = [];
+        const flushStatics = () => {
+            if (!staticEntries.length) {
+                return;
+            }
+            segments.push(`{ ${staticEntries.join(', ')} }`);
+            staticEntries = [];
+        };
+        attributes.forEach(attribute => {
+            if (attribute.type === 'JSXSpreadAttribute') {
+                flushStatics();
+                segments.push(this.compileExpression(attribute.argument));
+                return;
+            }
+            const name = this.compileAttributeName(attribute.name);
+            let value;
+            if (!attribute.value) {
+                value = 'true';
+            }
+            else if (attribute.value.type === 'Literal') {
+                value = JSON.stringify(attribute.value.value);
+            }
+            else if (attribute.value.type === 'JSXExpressionContainer') {
+                if (attribute.value.expression.type === 'JSXEmptyExpression') {
+                    return;
+                }
+                value = this.compileExpression(attribute.value.expression);
+            }
+            else {
+                value = 'undefined';
+            }
+            staticEntries.push(`${JSON.stringify(name)}: ${value}`);
+        });
+        flushStatics();
+        if (!segments.length) {
+            return 'null';
+        }
+        if (segments.length === 1) {
+            return segments[0];
+        }
+        return `__jsxReactMergeProps(${segments.join(', ')})`;
+    }
+    compileAttributeName(name) {
+        switch (name.type) {
+            case 'JSXIdentifier':
+                return name.name;
+            case 'JSXNamespacedName':
+                return `${name.namespace.name}:${name.name.name}`;
+            case 'JSXMemberExpression':
+                return `${this.compileAttributeName(name.object)}.${name.property.name}`;
+            default:
+                /* c8 ignore next */
+                return '';
+        }
+    }
+    compileTagName(name) {
+        if (!name) {
+            /* c8 ignore next */
+            throw new Error('[jsx-loader] Encountered JSX element without a tag name.');
+        }
+        if (name.type === 'JSXIdentifier') {
+            if (isLoaderPlaceholderIdentifier(name) && name.name) {
+                const resolved = this.placeholderMap.get(name.name);
+                if (!resolved) {
+                    /* c8 ignore next 3 */
+                    throw new Error('[jsx-loader] Unable to resolve placeholder for tag expression.');
+                }
+                return resolved;
+            }
+            if (/^[A-Z]/.test(name.name)) {
+                return name.name;
+            }
+            return JSON.stringify(name.name);
+        }
+        if (name.type === 'JSXMemberExpression') {
+            const object = this.compileTagName(name.object);
+            return `${object}.${name.property.name}`;
+        }
+        if (name.type === 'JSXNamespacedName') {
+            return JSON.stringify(`${name.namespace.name}:${name.name.name}`);
+        }
+        /* c8 ignore next */
+        throw new Error('[jsx-loader] Unsupported tag expression in react mode.');
+    }
+    compileExpression(node) {
+        if (node.type === 'JSXElement' || node.type === 'JSXFragment') {
+            return this.compileNode(node);
+        }
+        if (node.type === 'Identifier') {
+            const resolved = this.placeholderMap.get(node.name);
+            if (resolved) {
+                return resolved;
+            }
+            return node.name;
+        }
+        if ('range' in node && Array.isArray(node.range)) {
+            throw new Error('[jsx-loader] Unable to inline complex expressions in react mode.');
+        }
+        /* c8 ignore next */
+        throw new Error('[jsx-loader] Unable to compile expression for react mode.');
+    }
+    buildCreateElement(type, props, children) {
+        const args = [type, props];
+        if (children.length) {
+            args.push(children.join(', '));
+        }
+        return `__jsxReact(${args.join(', ')})`;
+    }
+}
 const stripTrailingWhitespace = (value) => value.replace(/\s+$/g, '');
 const stripLeadingWhitespace = (value) => value.replace(/^\s+/g, '');
 const getTemplateExpressionContext = (left, right) => {
@@ -43,6 +205,24 @@ const TEMPLATE_PARSER_OPTIONS = {
     preserveParens: true,
 };
 const DEFAULT_TAGS = ['jsx', 'reactJsx'];
+const DEFAULT_MODE = 'runtime';
+const HELPER_SNIPPETS = {
+    react: `const __jsxReactMergeProps = (...sources) => Object.assign({}, ...sources)
+const __jsxReact = (type, props, ...children) => React.createElement(type, props, ...children)
+`,
+};
+const parseLoaderMode = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    switch (value) {
+        case 'runtime':
+        case 'react':
+            return value;
+        default:
+            return null;
+    }
+};
 const escapeTemplateChunk = (chunk) => chunk.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\${/g, '\\${');
 const formatParserError = (error) => {
     let message = `[jsx-loader] ${error.message}`;
@@ -81,10 +261,12 @@ const walkAst = (node, visitor) => {
 const shouldInterpolateName = (name) => /^[A-Z]/.test(name.name);
 const addSlot = (slots, source, range) => {
     if (!range) {
+        /* c8 ignore next */
         return;
     }
     const [start, end] = range;
     if (start === end) {
+        /* c8 ignore next */
         return;
     }
     slots.push({
@@ -112,6 +294,7 @@ const collectSlots = (program, source) => {
                 break;
             }
             default:
+                /* c8 ignore next */
                 break;
         }
     };
@@ -164,6 +347,7 @@ const renderTemplateWithSlots = (source, slots) => {
     let output = '';
     slots.forEach(slot => {
         if (slot.start < cursor) {
+            /* c8 ignore next */
             throw new Error('Overlapping JSX expressions detected inside template literal.');
         }
         output += escapeTemplateChunk(source.slice(cursor, slot.start));
@@ -191,6 +375,22 @@ const getTaggedTemplateName = (node) => {
     }
     return tagNode.name;
 };
+const extractJsxRoot = (program) => {
+    for (const statement of program.body) {
+        if (statement.type === 'ExpressionStatement') {
+            const expression = statement.expression;
+            if (expression.type === 'JSXElement' || expression.type === 'JSXFragment') {
+                return expression;
+            }
+        }
+    }
+    throw new Error('[jsx-loader] Expected the template to contain a single JSX root node.');
+};
+const normalizeJsxTextValue = (value) => {
+    const collapsed = value.replace(/\r/g, '').replace(/\n\s+/g, ' ');
+    const trimmed = collapsed.trim();
+    return trimmed.length > 0 ? trimmed : '';
+};
 const TAG_PLACEHOLDER_PREFIX = '__JSX_LOADER_TAG_EXPR_';
 const buildTemplateSource = (quasis, expressions, source, tag) => {
     const placeholderMap = new Map();
@@ -217,6 +417,7 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
     quasis.forEach((quasi, index) => {
         let chunk = quasi.value.cooked;
         if (typeof chunk !== 'string') {
+            /* c8 ignore next */
             chunk = quasi.value.raw ?? '';
         }
         if (trimStartNext > 0) {
@@ -231,6 +432,7 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
         const start = expression.start ?? null;
         const end = expression.end ?? null;
         if (start === null || end === null) {
+            /* c8 ignore next */
             throw new Error('Unable to read template expression source range.');
         }
         const nextChunk = quasis[index + 1];
@@ -287,8 +489,20 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
 const restoreTemplatePlaceholders = (code, placeholders) => placeholders.reduce((result, placeholder) => {
     return result.split(placeholder.marker).join(`\${${placeholder.code}}`);
 }, code);
+const compileReactTemplate = (templateSource, placeholders, resourcePath) => {
+    const parsed = parseSync(`${resourcePath}?jsx-react-template`, templateSource, TEMPLATE_PARSER_OPTIONS);
+    if (parsed.errors.length > 0) {
+        throw new Error(formatParserError(parsed.errors[0]));
+    }
+    const root = extractJsxRoot(parsed.program);
+    const builder = new ReactTemplateBuilder(placeholders);
+    return builder.compile(root);
+};
 const isLoaderPlaceholderIdentifier = (node) => {
-    if (node?.type !== 'Identifier' || typeof node.name !== 'string') {
+    if (!node ||
+        (node.type !== 'Identifier' && node.type !== 'JSXIdentifier') ||
+        typeof node.name !== 'string') {
+        /* c8 ignore next */
         return false;
     }
     return (node.name.startsWith(TEMPLATE_EXPR_PLACEHOLDER_PREFIX) ||
@@ -307,28 +521,47 @@ const transformSource = (source, config) => {
         }
     });
     if (!taggedTemplates.length) {
-        return source;
+        return { code: source, helpers: [] };
     }
     const magic = new MagicString(source);
     let mutated = false;
+    const helperKinds = new Set();
     taggedTemplates
         .sort((a, b) => b.node.start - a.node.start)
         .forEach(entry => {
         const { node, tagName } = entry;
+        const mode = config.tagModes.get(tagName) ?? DEFAULT_MODE;
         const quasi = node.quasi;
         const templateSource = buildTemplateSource(quasi.quasis, quasi.expressions, source, tagName);
-        const { code, changed } = transformTemplateLiteral(templateSource.source, config.resourcePath);
-        const restored = restoreTemplatePlaceholders(code, templateSource.placeholders);
-        const templateChanged = changed || templateSource.mutated;
-        if (!templateChanged) {
+        if (mode === 'runtime') {
+            const { code, changed } = transformTemplateLiteral(templateSource.source, config.resourcePath);
+            const restored = restoreTemplatePlaceholders(code, templateSource.placeholders);
+            const templateChanged = changed || templateSource.mutated;
+            if (!templateChanged) {
+                return;
+            }
+            const tagSource = source.slice(node.tag.start, node.tag.end);
+            const replacement = `${tagSource}\`${restored}\``;
+            magic.overwrite(node.start, node.end, replacement);
+            mutated = true;
+            return;
+        }
+        if (mode === 'react') {
+            const compiled = compileReactTemplate(templateSource.source, templateSource.placeholders, config.resourcePath);
+            helperKinds.add('react');
+            magic.overwrite(node.start, node.end, compiled);
+            mutated = true;
             return;
         }
-        const tagSource = source.slice(node.tag.start, node.tag.end);
-        const replacement = `${tagSource}\`${restored}\``;
-        magic.overwrite(node.start, node.end, replacement);
-        mutated = true;
+        /* c8 ignore next */
+        throw new Error(`[jsx-loader] Transformation mode "${mode}" not implemented yet for tag "${tagName}".`);
     });
-    return mutated ? magic.toString() : source;
+    return {
+        code: mutated ? magic.toString() : source,
+        helpers: Array.from(helperKinds)
+            .map(kind => HELPER_SNIPPETS[kind])
+            .filter(Boolean),
+    };
 };
 export default function jsxLoader(input) {
     const callback = this.async();
@@ -343,13 +576,37 @@ export default function jsxLoader(input) {
             : legacyTag
                 ? [legacyTag]
                 : DEFAULT_TAGS;
-        const tags = Array.from(new Set(tagList));
+        const tagModes = new Map();
+        const configuredTagModes = options.tagModes && typeof options.tagModes === 'object'
+            ? options.tagModes
+            : undefined;
+        if (configuredTagModes) {
+            Object.entries(configuredTagModes).forEach(([tagName, mode]) => {
+                const parsed = parseLoaderMode(mode);
+                if (!parsed || typeof tagName !== 'string' || !tagName.length) {
+                    return;
+                }
+                tagModes.set(tagName, parsed);
+            });
+        }
+        const defaultMode = parseLoaderMode(options.mode) ?? DEFAULT_MODE;
+        const tags = Array.from(new Set([...tagList, ...tagModes.keys()]));
+        tags.forEach(tagName => {
+            if (!tagModes.has(tagName)) {
+                tagModes.set(tagName, defaultMode);
+            }
+        });
         const source = typeof input === 'string' ? input : input.toString('utf8');
-        const output = transformSource(source, {
+        const { code, helpers } = transformSource(source, {
             resourcePath: this.resourcePath,
             tags,
+            tagModes,
         });
-        callback(null, output);
+        if (helpers.length) {
+            callback(null, `${code}\n${helpers.join('\n')}`);
+            return;
+        }
+        callback(null, code);
     }
     catch (error) {
         callback(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.2.0-rc.1",
+  "version": "1.2.0-rc.3",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere without a build step.",
   "keywords": [
     "jsx runtime",
@@ -63,6 +63,7 @@
     "prettier": "prettier -w .",
     "test": "vitest run --coverage",
     "test:watch": "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",
     "dev": "vite dev --config vite.config.ts",
@@ -75,15 +76,17 @@
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@knighted/duel": "^2.1.6",
-    "@types/node": "^22.10.1",
+    "@oxc-project/types": "^0.99.0",
+    "@playwright/test": "^1.57.0",
     "@rspack/core": "^1.0.5",
     "@types/jsdom": "^27.0.0",
+    "@types/node": "^22.10.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@vitest/coverage-v8": "^4.0.14",
     "eslint": "^9.39.1",
     "eslint-plugin-n": "^17.10.3",
-    "@oxc-project/types": "^0.99.0",
+    "eslint-plugin-playwright": "^2.4.0",
     "http-server": "^14.1.1",
     "jsdom": "^27.2.0",
     "lit": "^3.2.1",
@@ -103,9 +106,9 @@
     "oxc-parser": "^0.99.0"
   },
   "peerDependencies": {
-    "react": ">=18",
     "jsdom": "*",
-    "linkedom": "*"
+    "linkedom": "*",
+    "react": ">=18"
   },
   "peerDependenciesMeta": {
     "react": {