@knighted/jsx 1.5.1 → 1.6.0

package/dist/cjs/loader/jsx.cjs

@@ -6,6 +6,7 @@ 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 template_diagnostics_js_1 = require("../internal/template-diagnostics.cjs");
 const createPlaceholderMap = (placeholders) => new Map(placeholders.map(entry => [entry.marker, entry.code]));
 class ReactTemplateBuilder {
     placeholderMap;
@@ -165,6 +166,9 @@ class ReactTemplateBuilder {
             throw new Error('[jsx-loader] Unable to inline complex expressions in react mode.');
         }
         /* c8 ignore next */
+        /* v8 ignore next */
+        /* istanbul ignore next */
+        // Should never happen because OXC always annotates expression ranges.
         throw new Error('[jsx-loader] Unable to compile expression for react mode.');
     }
     buildCreateElement(type, props, children) {
@@ -276,11 +280,15 @@ const shouldInterpolateName = (name) => /^[A-Z]/.test(name.name);
 const addSlot = (slots, source, range) => {
     if (!range) {
         /* c8 ignore next */
+        /* v8 ignore next */
+        // OXC always provides ranges; guard defends against malformed AST nodes.
         return;
     }
     const [start, end] = range;
     if (start === end) {
         /* c8 ignore next */
+        /* v8 ignore next */
+        // Zero-length ranges indicate parser bugs and would emit empty slices.
         return;
     }
     slots.push({
@@ -293,6 +301,9 @@ const collectSlots = (program, source) => {
     const slots = [];
     const recordComponentName = (name) => {
         if (!name) {
+            /* c8 ignore next */
+            /* v8 ignore next */
+            // JSX elements emitted by OXC always carry a name; this is defensive.
             return;
         }
         switch (name.type) {
@@ -362,6 +373,8 @@ const renderTemplateWithSlots = (source, slots) => {
     slots.forEach(slot => {
         if (slot.start < cursor) {
             /* c8 ignore next */
+            /* v8 ignore next */
+            // Slots are generated from non-overlapping JSX ranges; this protects against parser regressions.
             throw new Error('Overlapping JSX expressions detected inside template literal.');
         }
         output += escapeTemplateChunk(source.slice(cursor, slot.start));
@@ -371,10 +384,12 @@ const renderTemplateWithSlots = (source, slots) => {
     output += escapeTemplateChunk(source.slice(cursor));
     return { code: output, changed: slots.length > 0 };
 };
-const transformTemplateLiteral = (templateSource, resourcePath) => {
+const transformTemplateLiteral = (templateSource, resourcePath, tagName, templates, diagnostics) => {
     const result = (0, oxc_parser_1.parseSync)(`${resourcePath}?jsx-template`, templateSource, TEMPLATE_PARSER_OPTIONS);
     if (result.errors.length > 0) {
-        throw new Error(formatParserError(result.errors[0]));
+        throw new Error((0, template_diagnostics_js_1.formatTaggedTemplateParserError)(tagName, templates, diagnostics, result.errors[0], {
+            label: 'jsx-loader',
+        }));
     }
     const slots = collectSlots(result.program, templateSource);
     return renderTemplateWithSlots(templateSource, slots);
@@ -443,6 +458,25 @@ const normalizeJsxTextSegments = (value, placeholders) => {
     return segments;
 };
 const TAG_PLACEHOLDER_PREFIX = '__JSX_LOADER_TAG_EXPR_';
+const materializeTemplateStrings = (quasis) => {
+    const cooked = [];
+    const raw = [];
+    quasis.forEach(quasi => {
+        const value = quasi.value;
+        const cookedChunk = typeof value.cooked === 'string' ? value.cooked : (value.raw ?? '');
+        const rawChunk = typeof value.raw === 'string' ? value.raw : cookedChunk;
+        cooked.push(cookedChunk);
+        raw.push(rawChunk);
+    });
+    const templates = cooked;
+    Object.defineProperty(templates, 'raw', {
+        value: raw,
+        writable: false,
+        configurable: false,
+        enumerable: false,
+    });
+    return templates;
+};
 const buildTemplateSource = (quasis, expressions, source, tag) => {
     const placeholderMap = new Map();
     const tagPlaceholderMap = new Map();
@@ -450,6 +484,7 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
     let placeholderIndex = 0;
     let trimStartNext = 0;
     let mutated = false;
+    const expressionRanges = [];
     const registerMarker = (code, isTag) => {
         if (isTag) {
             const existing = tagPlaceholderMap.get(code);
@@ -465,10 +500,18 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
         placeholderMap.set(marker, code);
         return marker;
     };
+    const appendInsertion = (expressionIndex, insertion) => {
+        const start = template.length;
+        template += insertion;
+        const end = template.length;
+        expressionRanges.push({ index: expressionIndex, sourceStart: start, sourceEnd: end });
+    };
     quasis.forEach((quasi, index) => {
         let chunk = quasi.value.cooked;
         if (typeof chunk !== 'string') {
             /* c8 ignore next */
+            /* v8 ignore next */
+            // Cooked text is always available for valid templates; fall back shields invalid escape sequences.
             chunk = quasi.value.raw ?? '';
         }
         if (trimStartNext > 0) {
@@ -480,10 +523,13 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
         if (!expression) {
             return;
         }
+        const expressionIndex = index;
         const start = expression.start ?? null;
         const end = expression.end ?? null;
         if (start === null || end === null) {
             /* c8 ignore next */
+            /* v8 ignore next */
+            // Expressions parsed from tagged templates always include start/end ranges.
             throw new Error('Unable to read template expression source range.');
         }
         const nextChunk = quasis[index + 1];
@@ -493,7 +539,8 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
         const code = source.slice(start, end);
         const marker = registerMarker(code, context.type === 'tag');
         const appendMarker = (wrapper) => {
-            template += wrapper ? wrapper(marker) : marker;
+            const insertion = wrapper ? wrapper(marker) : marker;
+            appendInsertion(expressionIndex, insertion);
         };
         switch (context.type) {
             case 'tag':
@@ -535,15 +582,22 @@ const buildTemplateSource = (quasis, expressions, source, tag) => {
             marker,
             code,
         })),
+        diagnostics: { expressionRanges },
     };
 };
 const restoreTemplatePlaceholders = (code, placeholders) => placeholders.reduce((result, placeholder) => {
     return result.split(placeholder.marker).join(`\${${placeholder.code}}`);
 }, code);
-const compileReactTemplate = (templateSource, placeholders, resourcePath) => {
+const createInlineSourceMapComment = (map) => {
+    const payload = Buffer.from(JSON.stringify(map), 'utf8').toString('base64');
+    return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${payload}`;
+};
+const compileReactTemplate = (templateSource, placeholders, resourcePath, tagName, templates, diagnostics) => {
     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]));
+        throw new Error((0, template_diagnostics_js_1.formatTaggedTemplateParserError)(tagName, templates, diagnostics, parsed.errors[0], {
+            label: 'jsx-loader',
+        }));
     }
     const root = extractJsxRoot(parsed.program);
     const builder = new ReactTemplateBuilder(placeholders);
@@ -554,12 +608,14 @@ const isLoaderPlaceholderIdentifier = (node) => {
         (node.type !== 'Identifier' && node.type !== 'JSXIdentifier') ||
         typeof node.name !== 'string') {
         /* c8 ignore next */
+        /* v8 ignore next */
+        // Visitor only calls this helper with identifier-like nodes; guard prevents crashes on malformed ASTs.
         return false;
     }
     return (node.name.startsWith(TEMPLATE_EXPR_PLACEHOLDER_PREFIX) ||
         node.name.startsWith(TAG_PLACEHOLDER_PREFIX));
 };
-const transformSource = (source, config) => {
+const transformSource = (source, config, options) => {
     const ast = (0, oxc_parser_1.parseSync)(config.resourcePath, source, MODULE_PARSER_OPTIONS);
     if (ast.errors.length > 0) {
         throw new Error(formatParserError(ast.errors[0]));
@@ -572,7 +628,7 @@ const transformSource = (source, config) => {
         }
     });
     if (!taggedTemplates.length) {
-        return { code: source, helpers: [] };
+        return { code: source, mutated: false };
     }
     const magic = new magic_string_1.default(source);
     let mutated = false;
@@ -584,8 +640,9 @@ const transformSource = (source, config) => {
         const mode = config.tagModes.get(tagName) ?? DEFAULT_MODE;
         const quasi = node.quasi;
         const templateSource = buildTemplateSource(quasi.quasis, quasi.expressions, source, tagName);
+        const templateStrings = materializeTemplateStrings(quasi.quasis);
         if (mode === 'runtime') {
-            const { code, changed } = transformTemplateLiteral(templateSource.source, config.resourcePath);
+            const { code, changed } = transformTemplateLiteral(templateSource.source, config.resourcePath, tagName, templateStrings, templateSource.diagnostics);
             const restored = restoreTemplatePlaceholders(code, templateSource.placeholders);
             const templateChanged = changed || templateSource.mutated;
             if (!templateChanged) {
@@ -598,20 +655,37 @@ const transformSource = (source, config) => {
             return;
         }
         if (mode === 'react') {
-            const compiled = compileReactTemplate(templateSource.source, templateSource.placeholders, config.resourcePath);
+            const compiled = compileReactTemplate(templateSource.source, templateSource.placeholders, config.resourcePath, tagName, templateStrings, templateSource.diagnostics);
             helperKinds.add('react');
             magic.overwrite(node.start, node.end, compiled);
             mutated = true;
             return;
         }
         /* c8 ignore next */
+        /* v8 ignore next */
+        // Modes are validated during option parsing; this fallback guards future extensions.
         throw new Error(`[jsx-loader] Transformation mode "${mode}" not implemented yet for tag "${tagName}".`);
     });
+    const helperSource = Array.from(helperKinds)
+        .map(kind => HELPER_SNIPPETS[kind])
+        .filter(Boolean)
+        .join('\n');
+    if (helperSource) {
+        magic.append(`\n${helperSource}`);
+        mutated = true;
+    }
+    const code = mutated ? magic.toString() : source;
+    const map = options?.sourceMap && mutated
+        ? magic.generateMap({
+            hires: true,
+            source: config.resourcePath,
+            includeContent: true,
+        })
+        : undefined;
     return {
-        code: mutated ? magic.toString() : source,
-        helpers: Array.from(helperKinds)
-            .map(kind => HELPER_SNIPPETS[kind])
-            .filter(Boolean),
+        code,
+        map,
+        mutated,
     };
 };
 function jsxLoader(input) {
@@ -648,16 +722,14 @@ function jsxLoader(input) {
             }
         });
         const source = typeof input === 'string' ? input : input.toString('utf8');
-        const { code, helpers } = transformSource(source, {
+        const enableSourceMap = options.sourceMap === true;
+        const { code, map } = transformSource(source, {
             resourcePath: this.resourcePath,
             tags,
             tagModes,
-        });
-        if (helpers.length) {
-            callback(null, `${code}\n${helpers.join('\n')}`);
-            return;
-        }
-        callback(null, code);
+        }, { sourceMap: enableSourceMap });
+        const output = map && enableSourceMap ? `${code}\n${createInlineSourceMapComment(map)}` : code;
+        callback(null, output, map);
     }
     catch (error) {
         callback(error);

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

@@ -1,4 +1,5 @@
-type LoaderCallback = (err: Error | null, content?: string) => void;
+import { type SourceMap } from 'magic-string';
+type LoaderCallback = (error: Error | null, content?: string, map?: SourceMap | null) => void;
 type LoaderContext<TOptions> = {
     resourcePath: string;
     async(): LoaderCallback;
@@ -24,6 +25,10 @@ type LoaderOptions = {
      * Optional per-tag override of the transformation mode. Keys map to tag names.
      */
     tagModes?: Record<string, LoaderMode | undefined>;
+    /**
+     * When true, generate inline source maps for mutated files.
+     */
+    sourceMap?: boolean;
 };
 export default function jsxLoader(this: LoaderContext<LoaderOptions>, input: string | Buffer): void;
 export {};

package/dist/cjs/node/bootstrap.cjs

@@ -1,3 +1,7 @@
+import { createRequire } from 'node:module';
+const nodeRequire = createRequire(import.meta.url);
+let requireOverride = null;
+const resolveRequire = () => requireOverride ?? nodeRequire;
 const DOM_TEMPLATE = '<!doctype html><html><body></body></html>';
 const GLOBAL_KEYS = [
     'window',
@@ -23,13 +27,13 @@ const assignGlobalTargets = (windowObj) => {
         }
     });
 };
-const loadLinkedom = async () => {
-    const { parseHTML } = await import('linkedom');
+const loadLinkedom = () => {
+    const { parseHTML } = resolveRequire()('linkedom');
     const { window } = parseHTML(DOM_TEMPLATE);
     return window;
 };
-const loadJsdom = async () => {
-    const { JSDOM } = await import('jsdom');
+const loadJsdom = () => {
+    const { JSDOM } = resolveRequire()('jsdom');
     const { window } = new JSDOM(DOM_TEMPLATE);
     return window;
 };
@@ -52,11 +56,11 @@ const selectLoaders = () => {
     }
     return [loadLinkedom, loadJsdom];
 };
-const createShimWindow = async () => {
+const createShimWindow = () => {
     const errors = [];
     for (const loader of selectLoaders()) {
         try {
-            return await loader();
+            return loader();
         }
         catch (error) {
             errors.push(error);
@@ -65,19 +69,15 @@ const createShimWindow = async () => {
     const help = 'Unable to bootstrap a DOM-like environment. Install "linkedom" or "jsdom" (both optional peer dependencies) or set KNIGHTED_JSX_NODE_SHIM to pick one explicitly.';
     throw new AggregateError(errors, help);
 };
-let bootstrapPromise = null;
-export const ensureNodeDom = async () => {
-    if (hasDom()) {
+let bootstrapped = false;
+export const ensureNodeDom = () => {
+    if (hasDom() || bootstrapped) {
         return;
     }
-    if (!bootstrapPromise) {
-        bootstrapPromise = (async () => {
-            const windowObj = await createShimWindow();
-            assignGlobalTargets(windowObj);
-        })().catch(error => {
-            bootstrapPromise = null;
-            throw error;
-        });
-    }
-    return bootstrapPromise;
+    const windowObj = createShimWindow();
+    assignGlobalTargets(windowObj);
+    bootstrapped = true;
+};
+export const __setNodeRequireForTesting = (mockRequire) => {
+    requireOverride = mockRequire;
 };

package/dist/cjs/node/bootstrap.d.cts

@@ -1 +1,2 @@
-export declare const ensureNodeDom: () => Promise<void>;
+export declare const ensureNodeDom: () => void;
+export declare const __setNodeRequireForTesting: (mockRequire: NodeJS.Require | null) => void;

package/dist/cjs/node/debug/index.cjs

@@ -0,0 +1,6 @@
+import { enableJsxDebugDiagnostics } from '../../debug/diagnostics.cjs';
+import { ensureNodeDom } from '../bootstrap.cjs';
+import { jsx as baseJsx } from '../../jsx.cjs';
+enableJsxDebugDiagnostics({ mode: 'always' });
+ensureNodeDom();
+export const jsx = baseJsx;

package/dist/cjs/node/debug/index.d.cts

@@ -0,0 +1,2 @@
+export declare const jsx: (templates: TemplateStringsArray, ...values: unknown[]) => import("../../jsx.cjs").JsxRenderable;
+export type { JsxRenderable, JsxComponent } from '../../jsx.cjs';

package/dist/cjs/node/index.cjs

@@ -1,4 +1,4 @@
 import { ensureNodeDom } from './bootstrap.cjs';
 import { jsx as baseJsx } from '../jsx.cjs';
-await ensureNodeDom();
+ensureNodeDom();
 export const jsx = baseJsx;

package/dist/cjs/react/react-jsx.cjs

@@ -127,7 +127,7 @@ const reactJsx = (templates, ...values) => {
     const build = (0, shared_js_1.buildTemplate)(templates, values);
     const result = (0, oxc_parser_1.parseSync)('inline.jsx', build.source, shared_js_1.parserOptions);
     if (result.errors.length > 0) {
-        throw new Error((0, shared_js_1.formatParserError)(result.errors[0]));
+        throw new Error((0, shared_js_1.formatTaggedTemplateParserError)('reactJsx', templates, build.diagnostics, result.errors[0]));
     }
     const root = (0, shared_js_1.extractRootNode)(result.program);
     const ctx = {

package/dist/cjs/runtime/shared.cjs

@@ -1,31 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildTemplate = exports.ensureBinding = exports.sanitizeIdentifier = exports.evaluateExpression = exports.collectPlaceholderNames = exports.normalizeJsxTextSegments = exports.walkAst = exports.getIdentifierName = exports.extractRootNode = exports.formatParserError = exports.parserOptions = exports.placeholderPattern = exports.PLACEHOLDER_PREFIX = void 0;
+exports.buildTemplate = exports.ensureBinding = exports.sanitizeIdentifier = exports.evaluateExpression = exports.collectPlaceholderNames = exports.normalizeJsxTextSegments = exports.walkAst = exports.getIdentifierName = exports.extractRootNode = exports.parserOptions = exports.formatParserError = exports.placeholderPattern = exports.PLACEHOLDER_PREFIX = exports.formatTaggedTemplateParserError = void 0;
+var template_diagnostics_js_1 = require("../internal/template-diagnostics.cjs");
+Object.defineProperty(exports, "formatTaggedTemplateParserError", { enumerable: true, get: function () { return template_diagnostics_js_1.formatTaggedTemplateParserError; } });
 const OPEN_TAG_RE = /<\s*$/;
 const CLOSE_TAG_RE = /<\/\s*$/;
 exports.PLACEHOLDER_PREFIX = '__KX_EXPR__';
 exports.placeholderPattern = new RegExp(`${exports.PLACEHOLDER_PREFIX}\\d+_\\d+__`, 'g');
 let invocationCounter = 0;
-exports.parserOptions = {
-    lang: 'jsx',
-    sourceType: 'module',
-    range: true,
-    preserveParens: true,
-};
 const formatParserError = (error) => {
     let message = `[oxc-parser] ${error.message}`;
-    if (error.labels?.length) {
-        const label = error.labels[0];
-        if (label.message) {
-            message += `\n${label.message}`;
-        }
+    const primaryLabel = error.labels?.[0];
+    if (primaryLabel?.message) {
+        message += `\n${primaryLabel.message}`;
     }
     if (error.codeframe) {
         message += `\n${error.codeframe}`;
     }
+    if (error.helpMessage) {
+        message += `\n${error.helpMessage}`;
+    }
     return message;
 };
 exports.formatParserError = formatParserError;
+exports.parserOptions = {
+    lang: 'jsx',
+    sourceType: 'module',
+    range: true,
+    preserveParens: true,
+};
 const extractRootNode = (program) => {
     for (const statement of program.body) {
         if (statement.type === 'ExpressionStatement') {
@@ -183,24 +186,40 @@ const buildTemplate = (strings, values) => {
     let source = raw[0] ?? '';
     const templateId = invocationCounter++;
     let placeholderIndex = 0;
+    const expressionRanges = [];
     for (let idx = 0; idx < values.length; idx++) {
         const chunk = raw[idx] ?? '';
         const nextChunk = raw[idx + 1] ?? '';
         const value = values[idx];
         const isTagNamePosition = OPEN_TAG_RE.test(chunk) || CLOSE_TAG_RE.test(chunk);
+        let insertion;
         if (isTagNamePosition && typeof value === 'function') {
             const binding = (0, exports.ensureBinding)(value, bindings, bindingLookup);
-            source += binding.name + nextChunk;
-            continue;
+            insertion = binding.name;
         }
-        if (isTagNamePosition && typeof value === 'string') {
-            source += value + nextChunk;
-            continue;
+        else if (isTagNamePosition && typeof value === 'string') {
+            insertion = value;
         }
-        const placeholder = `${exports.PLACEHOLDER_PREFIX}${templateId}_${placeholderIndex++}__`;
-        placeholders.set(placeholder, value);
-        source += placeholder + nextChunk;
-    }
-    return { source, placeholders, bindings };
+        else {
+            const placeholder = `${exports.PLACEHOLDER_PREFIX}${templateId}_${placeholderIndex++}__`;
+            placeholders.set(placeholder, value);
+            insertion = placeholder;
+        }
+        const sourceStart = source.length;
+        source += insertion;
+        const sourceEnd = source.length;
+        expressionRanges.push({
+            index: idx,
+            sourceStart,
+            sourceEnd,
+        });
+        source += nextChunk;
+    }
+    return {
+        source,
+        placeholders,
+        bindings,
+        diagnostics: { expressionRanges },
+    };
 };
 exports.buildTemplate = buildTemplate;

package/dist/cjs/runtime/shared.d.cts

@@ -1,7 +1,11 @@
 import type { Expression, JSXElement, JSXFragment, JSXIdentifier, JSXMemberExpression, JSXNamespacedName, Program } from '@oxc-project/types';
 import type { OxcError, ParserOptions } from 'oxc-parser';
+import type { TemplateDiagnostics } from '../internal/template-diagnostics.cjs';
+export { formatTaggedTemplateParserError } from '../internal/template-diagnostics.cjs';
+export type { TemplateDiagnostics, TemplateExpressionRange, } from '../internal/template-diagnostics.cjs';
 export declare const PLACEHOLDER_PREFIX = "__KX_EXPR__";
 export declare const placeholderPattern: RegExp;
+export declare const formatParserError: (error: OxcError) => string;
 type AnyTemplateFunction = (...args: any[]) => unknown;
 type AnyTemplateConstructor = abstract new (...args: any[]) => unknown;
 export type TemplateComponent = (AnyTemplateFunction | AnyTemplateConstructor) & {
@@ -16,6 +20,7 @@ export type TemplateBuildResult<TComponent extends TemplateComponent> = {
     source: string;
     placeholders: Map<string, unknown>;
     bindings: BindingEntry<TComponent>[];
+    diagnostics: TemplateDiagnostics;
 };
 export type TemplateContext<TComponent extends TemplateComponent> = {
     source: string;
@@ -23,7 +28,6 @@ export type TemplateContext<TComponent extends TemplateComponent> = {
     components: Map<string, TComponent>;
 };
 export declare const parserOptions: ParserOptions;
-export declare const formatParserError: (error: OxcError) => string;
 export declare const extractRootNode: (program: Program) => JSXElement | JSXFragment;
 export declare const getIdentifierName: (identifier: JSXIdentifier | JSXNamespacedName | JSXMemberExpression) => string;
 type AnyOxcNode = {
@@ -37,4 +41,3 @@ export declare const evaluateExpression: <TComponent extends TemplateComponent>(
 export declare const sanitizeIdentifier: (value: string) => string;
 export declare const ensureBinding: <TComponent extends TemplateComponent>(value: TComponent, bindings: BindingEntry<TComponent>[], bindingLookup: Map<TComponent, BindingEntry<TComponent>>) => BindingEntry<TComponent>;
 export declare const buildTemplate: <TComponent extends TemplateComponent>(strings: TemplateStringsArray, values: unknown[]) => TemplateBuildResult<TComponent>;
-export {};

package/dist/debug/diagnostics.d.ts

@@ -0,0 +1,6 @@
+export type JsxDiagnosticsMode = 'env' | 'always';
+export type EnableJsxDebugDiagnosticsOptions = {
+    mode?: JsxDiagnosticsMode;
+};
+export declare const enableJsxDebugDiagnostics: (options?: EnableJsxDebugDiagnosticsOptions) => void;
+export declare const disableJsxDebugDiagnostics: () => void;

package/dist/debug/diagnostics.js

@@ -0,0 +1,52 @@
+import { setAttributeDiagnosticsHooks, } from '../internal/attribute-resolution.js';
+import { setEventDiagnosticsHooks, } from '../internal/event-bindings.js';
+import { createDevError, describeValue, emitDevWarning, isDevEnvironment, } from '../internal/dev-environment.js';
+const isAsciiLowercase = (char) => char >= 'a' && char <= 'z';
+let diagnosticsMode = 'env';
+const shouldRunDiagnostics = () => diagnosticsMode === 'always' || (diagnosticsMode === 'env' && isDevEnvironment());
+const shouldForceWarnings = () => diagnosticsMode === 'always';
+const attributeDiagnostics = {
+    warnLowercaseEventProp(name) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        if (!name.startsWith('on') || name.startsWith('on:') || name.length < 3) {
+            return;
+        }
+        const indicator = name[2] ?? '';
+        if (!isAsciiLowercase(indicator)) {
+            return;
+        }
+        const suggestion = `${name.slice(0, 2)}${indicator.toUpperCase()}${name.slice(3)}`;
+        emitDevWarning(`Use camelCase DOM event props when targeting runtime jsx templates. Received "${name}"; did you mean "${suggestion}"?`, shouldForceWarnings());
+    },
+    ensureValidDangerouslySetInnerHTML(value) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw createDevError('dangerouslySetInnerHTML expects an object with a string __html field.');
+        }
+        const html = value.__html;
+        if (typeof html !== 'string') {
+            throw createDevError(`dangerouslySetInnerHTML.__html must be a string but received ${describeValue(html)}.`);
+        }
+    },
+};
+const eventDiagnostics = {
+    onInvalidHandler(propName, value) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        throw createDevError(`The "${propName}" prop expects a function, EventListenerObject, or descriptor ({ handler }) but received ${describeValue(value)}.`);
+    },
+};
+export const enableJsxDebugDiagnostics = (options) => {
+    diagnosticsMode = options?.mode ?? 'env';
+    setAttributeDiagnosticsHooks(attributeDiagnostics);
+    setEventDiagnosticsHooks(eventDiagnostics);
+};
+export const disableJsxDebugDiagnostics = () => {
+    setAttributeDiagnosticsHooks(null);
+    setEventDiagnosticsHooks(null);
+};

package/dist/debug/index.d.ts

@@ -0,0 +1,2 @@
+export { jsx } from '../jsx.js';
+export type { JsxRenderable, JsxComponent } from '../jsx.js';

package/dist/debug/index.js

@@ -0,0 +1,3 @@
+import { enableJsxDebugDiagnostics } from './diagnostics.js';
+enableJsxDebugDiagnostics({ mode: 'always' });
+export { jsx } from '../jsx.js';

package/dist/internal/attribute-resolution.d.ts

@@ -0,0 +1,15 @@
+import type { Expression, JSXAttribute, JSXElement, JSXFragment, JSXSpreadAttribute } from '@oxc-project/types';
+import type { TemplateComponent, TemplateContext } from '../runtime/shared.js';
+export type AttributeDiagnosticsHooks = {
+    warnLowercaseEventProp?: (name: string) => void;
+    ensureValidDangerouslySetInnerHTML?: (value: unknown) => void;
+};
+export declare const setAttributeDiagnosticsHooks: (hooks: AttributeDiagnosticsHooks | null) => void;
+export type Namespace = 'svg' | null;
+export type EvaluateExpressionWithNamespace<TComponent extends TemplateComponent> = (expression: Expression | JSXElement | JSXFragment, ctx: TemplateContext<TComponent>, namespace: Namespace) => unknown;
+export type ResolveAttributesDependencies<TComponent extends TemplateComponent> = {
+    getIdentifierName: (name: JSXAttribute['name']) => string;
+    evaluateExpressionWithNamespace: EvaluateExpressionWithNamespace<TComponent>;
+};
+export type ResolveAttributesFn<TComponent extends TemplateComponent> = (attributes: (JSXAttribute | JSXSpreadAttribute)[], ctx: TemplateContext<TComponent>, namespace: Namespace) => Record<string, unknown>;
+export declare const createResolveAttributes: <TComponent extends TemplateComponent>(deps: ResolveAttributesDependencies<TComponent>) => ResolveAttributesFn<TComponent>;

package/dist/internal/attribute-resolution.js

@@ -0,0 +1,50 @@
+let attributeDiagnostics = null;
+export const setAttributeDiagnosticsHooks = (hooks) => {
+    attributeDiagnostics = hooks;
+};
+const warnLowercaseEventProp = (name) => {
+    attributeDiagnostics?.warnLowercaseEventProp?.(name);
+};
+const ensureValidDangerouslySetInnerHTML = (value) => {
+    attributeDiagnostics?.ensureValidDangerouslySetInnerHTML?.(value);
+};
+export const createResolveAttributes = (deps) => {
+    const { getIdentifierName, evaluateExpressionWithNamespace } = deps;
+    return (attributes, ctx, namespace) => {
+        const props = {};
+        const assignProp = (propName, propValue) => {
+            if (propName === 'dangerouslySetInnerHTML') {
+                ensureValidDangerouslySetInnerHTML(propValue);
+            }
+            props[propName] = propValue;
+        };
+        attributes.forEach(attribute => {
+            if (attribute.type === 'JSXSpreadAttribute') {
+                const spreadValue = evaluateExpressionWithNamespace(attribute.argument, ctx, namespace);
+                if (spreadValue &&
+                    typeof spreadValue === 'object' &&
+                    !Array.isArray(spreadValue)) {
+                    Object.assign(props, spreadValue);
+                }
+                return;
+            }
+            const name = getIdentifierName(attribute.name);
+            warnLowercaseEventProp(name);
+            if (!attribute.value) {
+                assignProp(name, true);
+                return;
+            }
+            if (attribute.value.type === 'Literal') {
+                assignProp(name, attribute.value.value);
+                return;
+            }
+            if (attribute.value.type === 'JSXExpressionContainer') {
+                if (attribute.value.expression.type === 'JSXEmptyExpression') {
+                    return;
+                }
+                assignProp(name, evaluateExpressionWithNamespace(attribute.value.expression, ctx, namespace));
+            }
+        });
+        return props;
+    };
+};

package/dist/internal/dev-environment.d.ts

@@ -0,0 +1,4 @@
+export declare const isDevEnvironment: () => boolean;
+export declare const describeValue: (value: unknown) => string;
+export declare const createDevError: (message: string) => Error;
+export declare const emitDevWarning: (message: string, force?: boolean) => void;