@knighted/jsx 1.5.2 → 1.6.0

package/README.md

@@ -19,6 +19,7 @@ A runtime JSX template tag backed by the [`oxc-parser`](https://github.com/oxc-p
 - [Loader integration](#loader-integration)
 - [Node / SSR usage](#node--ssr-usage)
 - [Browser usage](#browser-usage)
+- [Development diagnostics](docs/development-diagnostics.md)
 - [TypeScript plugin](docs/ts-plugin.md)
 - [TypeScript guide](docs/typescript.md)
 - [Component testing](docs/testing.md)

package/dist/cjs/debug/diagnostics.cjs

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disableJsxDebugDiagnostics = exports.enableJsxDebugDiagnostics = void 0;
+const attribute_resolution_js_1 = require("../internal/attribute-resolution.cjs");
+const event_bindings_js_1 = require("../internal/event-bindings.cjs");
+const dev_environment_js_1 = require("../internal/dev-environment.cjs");
+const isAsciiLowercase = (char) => char >= 'a' && char <= 'z';
+let diagnosticsMode = 'env';
+const shouldRunDiagnostics = () => diagnosticsMode === 'always' || (diagnosticsMode === 'env' && (0, dev_environment_js_1.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)}`;
+        (0, dev_environment_js_1.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 (0, dev_environment_js_1.createDevError)('dangerouslySetInnerHTML expects an object with a string __html field.');
+        }
+        const html = value.__html;
+        if (typeof html !== 'string') {
+            throw (0, dev_environment_js_1.createDevError)(`dangerouslySetInnerHTML.__html must be a string but received ${(0, dev_environment_js_1.describeValue)(html)}.`);
+        }
+    },
+};
+const eventDiagnostics = {
+    onInvalidHandler(propName, value) {
+        if (!shouldRunDiagnostics()) {
+            return;
+        }
+        throw (0, dev_environment_js_1.createDevError)(`The "${propName}" prop expects a function, EventListenerObject, or descriptor ({ handler }) but received ${(0, dev_environment_js_1.describeValue)(value)}.`);
+    },
+};
+const enableJsxDebugDiagnostics = (options) => {
+    diagnosticsMode = options?.mode ?? 'env';
+    (0, attribute_resolution_js_1.setAttributeDiagnosticsHooks)(attributeDiagnostics);
+    (0, event_bindings_js_1.setEventDiagnosticsHooks)(eventDiagnostics);
+};
+exports.enableJsxDebugDiagnostics = enableJsxDebugDiagnostics;
+const disableJsxDebugDiagnostics = () => {
+    (0, attribute_resolution_js_1.setAttributeDiagnosticsHooks)(null);
+    (0, event_bindings_js_1.setEventDiagnosticsHooks)(null);
+};
+exports.disableJsxDebugDiagnostics = disableJsxDebugDiagnostics;

package/dist/cjs/debug/diagnostics.d.cts

@@ -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/cjs/debug/index.cjs

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsx = void 0;
+const diagnostics_js_1 = require("./diagnostics.cjs");
+(0, diagnostics_js_1.enableJsxDebugDiagnostics)({ mode: 'always' });
+var jsx_js_1 = require("../jsx.cjs");
+Object.defineProperty(exports, "jsx", { enumerable: true, get: function () { return jsx_js_1.jsx; } });

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

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

package/dist/cjs/internal/attribute-resolution.cjs

@@ -1,10 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createResolveAttributes = void 0;
+exports.createResolveAttributes = exports.setAttributeDiagnosticsHooks = void 0;
+let attributeDiagnostics = null;
+const setAttributeDiagnosticsHooks = (hooks) => {
+    attributeDiagnostics = hooks;
+};
+exports.setAttributeDiagnosticsHooks = setAttributeDiagnosticsHooks;
+const warnLowercaseEventProp = (name) => {
+    attributeDiagnostics?.warnLowercaseEventProp?.(name);
+};
+const ensureValidDangerouslySetInnerHTML = (value) => {
+    attributeDiagnostics?.ensureValidDangerouslySetInnerHTML?.(value);
+};
 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);
@@ -16,19 +33,20 @@ const createResolveAttributes = (deps) => {
                 return;
             }
             const name = getIdentifierName(attribute.name);
+            warnLowercaseEventProp(name);
             if (!attribute.value) {
-                props[name] = true;
+                assignProp(name, true);
                 return;
             }
             if (attribute.value.type === 'Literal') {
-                props[name] = attribute.value.value;
+                assignProp(name, attribute.value.value);
                 return;
             }
             if (attribute.value.type === 'JSXExpressionContainer') {
                 if (attribute.value.expression.type === 'JSXEmptyExpression') {
                     return;
                 }
-                props[name] = evaluateExpressionWithNamespace(attribute.value.expression, ctx, namespace);
+                assignProp(name, evaluateExpressionWithNamespace(attribute.value.expression, ctx, namespace));
             }
         });
         return props;

package/dist/cjs/internal/attribute-resolution.d.cts

@@ -1,5 +1,10 @@
 import type { Expression, JSXAttribute, JSXElement, JSXFragment, JSXSpreadAttribute } from '@oxc-project/types';
 import type { TemplateComponent, TemplateContext } from '../runtime/shared.cjs';
+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> = {

package/dist/cjs/internal/dev-environment.cjs

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitDevWarning = exports.createDevError = exports.describeValue = exports.isDevEnvironment = void 0;
+const DEV_PREFIX = '@knighted/jsx';
+const formatDevMessage = (message) => `${DEV_PREFIX}: ${message}`;
+const isDevEnvironment = () => typeof process !== 'undefined' && process.env?.KNIGHTED_JSX_DEBUG === '1';
+exports.isDevEnvironment = isDevEnvironment;
+const describeValue = (value) => {
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (typeof value === 'function') {
+        return value.name ? `function ${value.name}` : 'function';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (typeof value === 'object') {
+        const ctor = value.constructor;
+        if (ctor && typeof ctor.name === 'string' && ctor.name && ctor.name !== 'Object') {
+            return `${ctor.name} instance`;
+        }
+        return 'object';
+    }
+    return typeof value;
+};
+exports.describeValue = describeValue;
+const createDevError = (message) => new Error(formatDevMessage(message));
+exports.createDevError = createDevError;
+const emitDevWarning = (message, force = false) => {
+    if (!force && !(0, exports.isDevEnvironment)()) {
+        return;
+    }
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn(formatDevMessage(message));
+    }
+};
+exports.emitDevWarning = emitDevWarning;

package/dist/cjs/internal/dev-environment.d.cts

@@ -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;

package/dist/cjs/internal/event-bindings.cjs

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEventHandlerValue = exports.parseEventPropName = void 0;
+exports.resolveEventHandlerValue = exports.parseEventPropName = exports.setEventDiagnosticsHooks = void 0;
+let eventDiagnostics = null;
+const setEventDiagnosticsHooks = (hooks) => {
+    eventDiagnostics = hooks;
+};
+exports.setEventDiagnosticsHooks = setEventDiagnosticsHooks;
 const captureSuffix = 'Capture';
 const stripCaptureSuffix = (rawName) => {
     if (rawName.endsWith(captureSuffix)) {
@@ -54,11 +59,15 @@ const isEventHandlerDescriptor = (value) => {
     }
     return isEventListenerObject(handler);
 };
-const resolveEventHandlerValue = (value) => {
+const throwInvalidHandlerError = (propName, value) => {
+    eventDiagnostics?.onInvalidHandler?.(propName, value);
+};
+const resolveEventHandlerValue = (propName, value) => {
     if (typeof value === 'function' || isEventListenerObject(value)) {
         return { listener: value };
     }
     if (!isEventHandlerDescriptor(value)) {
+        throwInvalidHandlerError(propName, value);
         return null;
     }
     const descriptor = value;

package/dist/cjs/internal/event-bindings.d.cts

@@ -1,3 +1,7 @@
+export type EventDiagnosticsHooks = {
+    onInvalidHandler?: (propName: string, value: unknown) => void;
+};
+export declare const setEventDiagnosticsHooks: (hooks: EventDiagnosticsHooks | null) => void;
 export type ParsedEventBinding = {
     eventName: string;
     capture: boolean;
@@ -15,4 +19,4 @@ export type ResolvedEventHandler = {
     listener: EventListenerOrEventListenerObject;
     options?: AddEventListenerOptions;
 };
-export declare const resolveEventHandlerValue: (value: unknown) => ResolvedEventHandler | null;
+export declare const resolveEventHandlerValue: (propName: string, value: unknown) => ResolvedEventHandler | null;

package/dist/cjs/internal/template-diagnostics.cjs

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTaggedTemplateParserError = void 0;
+const DEFAULT_LABEL = 'oxc-parser';
+const buildTemplateDisplaySource = (templates) => {
+    const raw = templates.raw ?? templates;
+    let source = raw[0] ?? '';
+    const spans = [];
+    for (let idx = 0; idx < raw.length - 1; idx++) {
+        const label = '${expr#' + idx + '}';
+        const templateStart = source.length;
+        source += label;
+        const templateEnd = source.length;
+        spans.push({ index: idx, templateStart, templateEnd, label });
+        source += raw[idx + 1] ?? '';
+    }
+    return { source, spans };
+};
+const combineExpressionSpans = (diagnostics, templateSpans) => {
+    const templateSpanMap = new Map();
+    templateSpans.forEach(span => {
+        templateSpanMap.set(span.index, span);
+    });
+    return diagnostics.expressionRanges
+        .map(span => {
+        const templateSpan = templateSpanMap.get(span.index);
+        if (!templateSpan) {
+            return null;
+        }
+        const sourceLength = Math.max(0, span.sourceEnd - span.sourceStart);
+        const templateLength = Math.max(0, templateSpan.templateEnd - templateSpan.templateStart);
+        return {
+            sourceStart: span.sourceStart,
+            sourceEnd: span.sourceEnd,
+            templateStart: templateSpan.templateStart,
+            templateEnd: templateSpan.templateEnd,
+            delta: templateLength - sourceLength,
+        };
+    })
+        .filter((span) => Boolean(span))
+        .sort((a, b) => a.sourceStart - b.sourceStart);
+};
+const mapIndexToTemplate = (index, spans, templateLength) => {
+    if (!Number.isFinite(index) || index <= 0) {
+        return 0;
+    }
+    let delta = 0;
+    for (const span of spans) {
+        if (index < span.sourceStart) {
+            break;
+        }
+        if (index < span.sourceEnd) {
+            const relative = Math.max(0, index - span.sourceStart);
+            const templateSpanLength = Math.max(0, span.templateEnd - span.templateStart);
+            if (templateSpanLength === 0) {
+                return span.templateStart;
+            }
+            const clamped = Math.min(relative, Math.max(0, templateSpanLength - 1));
+            return span.templateStart + clamped;
+        }
+        delta += span.delta;
+    }
+    const mapped = index + delta;
+    if (mapped <= 0) {
+        return 0;
+    }
+    if (mapped >= templateLength) {
+        return templateLength;
+    }
+    return mapped;
+};
+const getLineAndColumnFromIndex = (source, index) => {
+    const limit = Math.max(0, Math.min(index, source.length));
+    let line = 1;
+    let column = 1;
+    for (let idx = 0; idx < limit; idx++) {
+        if (source.charCodeAt(idx) === 10) {
+            line++;
+            column = 1;
+            continue;
+        }
+        column++;
+    }
+    return { line, column };
+};
+const computeLineOffsets = (lines) => {
+    const offsets = [];
+    let cursor = 0;
+    lines.forEach((line, index) => {
+        offsets.push(cursor);
+        cursor += line.length;
+        if (index < lines.length - 1) {
+            cursor += 1;
+        }
+    });
+    return offsets;
+};
+const createPointerLine = (lineNumber, lineText, lineStartOffset, rangeStart, rangeEnd, startLine, endLine) => {
+    const lineEndOffset = lineStartOffset + lineText.length;
+    const overlapStart = Math.max(rangeStart, lineStartOffset);
+    const overlapEnd = Math.min(rangeEnd, lineEndOffset);
+    if (overlapEnd > overlapStart) {
+        const pointerStart = Math.max(0, overlapStart - lineStartOffset);
+        const pointerWidth = Math.max(1, overlapEnd - overlapStart);
+        return ' '.repeat(pointerStart) + '^'.repeat(pointerWidth);
+    }
+    if (lineText.length === 0 && lineNumber >= startLine && lineNumber <= endLine) {
+        return '^';
+    }
+    if (lineNumber === startLine) {
+        const caretPos = Math.max(0, rangeStart - lineStartOffset);
+        return ' '.repeat(Math.min(caretPos, lineText.length)) + '^';
+    }
+    return '';
+};
+const buildCodeFrame = (source, start, end, startLine, endLine) => {
+    if (!source.length) {
+        return '';
+    }
+    const lines = source.split('\n');
+    const offsets = computeLineOffsets(lines);
+    const frameStart = Math.max(1, startLine - 1);
+    const frameEnd = Math.min(lines.length, endLine + 1);
+    const gutterWidth = String(frameEnd).length;
+    const frame = [];
+    for (let lineNumber = frameStart; lineNumber <= frameEnd; lineNumber++) {
+        const lineText = lines[lineNumber - 1] ?? '';
+        const gutter = String(lineNumber).padStart(gutterWidth, ' ');
+        frame.push(`${gutter} | ${lineText}`);
+        const pointer = createPointerLine(lineNumber, lineText, offsets[lineNumber - 1] ?? 0, start, end, startLine, endLine);
+        if (pointer) {
+            frame.push(`${' '.repeat(gutterWidth)} | ${pointer}`);
+        }
+    }
+    return frame.join('\n');
+};
+const formatTaggedTemplateParserError = (tagName, templates, diagnostics, error, options) => {
+    const label = options?.label ?? DEFAULT_LABEL;
+    const fallback = `[${label}] ${error.message}`;
+    const primaryLabel = error.labels?.[0];
+    if (!primaryLabel) {
+        return fallback;
+    }
+    const { source: templateSource, spans } = buildTemplateDisplaySource(templates);
+    const combinedSpans = combineExpressionSpans(diagnostics, spans);
+    const mapIndex = (value) => {
+        const numeric = typeof value === 'number' ? value : 0;
+        return mapIndexToTemplate(numeric, combinedSpans, templateSource.length);
+    };
+    const startIndex = mapIndex(primaryLabel.start);
+    let endIndex = mapIndex(primaryLabel.end);
+    if (endIndex <= startIndex) {
+        endIndex = Math.min(templateSource.length, startIndex + 1);
+    }
+    const startLocation = getLineAndColumnFromIndex(templateSource, startIndex);
+    const endLocation = getLineAndColumnFromIndex(templateSource, Math.max(startIndex, endIndex - 1));
+    const codeframe = buildCodeFrame(templateSource, startIndex, endIndex, startLocation.line, endLocation.line);
+    let message = `[${label}] ${error.message}`;
+    message += `\n--> ${tagName} template:${startLocation.line}:${startLocation.column}`;
+    if (primaryLabel.message) {
+        message += `\n${primaryLabel.message}`;
+    }
+    if (codeframe) {
+        message += `\n${codeframe}`;
+    }
+    if (error.helpMessage) {
+        message += `\n${error.helpMessage}`;
+    }
+    return message;
+};
+exports.formatTaggedTemplateParserError = formatTaggedTemplateParserError;

package/dist/cjs/internal/template-diagnostics.d.cts

@@ -0,0 +1,13 @@
+import type { OxcError } from 'oxc-parser';
+export type TemplateExpressionRange = {
+    index: number;
+    sourceStart: number;
+    sourceEnd: number;
+};
+export type TemplateDiagnostics = {
+    expressionRanges: TemplateExpressionRange[];
+};
+export type TaggedTemplateFormatOptions = {
+    label?: string;
+};
+export declare const formatTaggedTemplateParserError: (tagName: string, templates: TemplateStringsArray, diagnostics: TemplateDiagnostics, error: OxcError, options?: TaggedTemplateFormatOptions) => string;

package/dist/cjs/jsx.cjs

@@ -116,7 +116,7 @@ const setDomProp = (element, name, value, namespace) => {
     }
     const eventBinding = (0, event_bindings_js_1.parseEventPropName)(name);
     if (eventBinding) {
-        const handlerValue = (0, event_bindings_js_1.resolveEventHandlerValue)(value);
+        const handlerValue = (0, event_bindings_js_1.resolveEventHandlerValue)(name, value);
         if (handlerValue) {
             let options = handlerValue.options ? { ...handlerValue.options } : undefined;
             if (eventBinding.capture) {
@@ -311,7 +311,7 @@ const jsx = (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)('jsx', templates, build.diagnostics, result.errors[0]));
     }
     const root = (0, shared_js_1.extractRootNode)(result.program);
     const ctx = {

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;
@@ -383,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);
@@ -455,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();
@@ -462,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);
@@ -477,6 +500,12 @@ 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') {
@@ -494,6 +523,7 @@ 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) {
@@ -509,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':
@@ -551,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);
@@ -577,7 +615,7 @@ const isLoaderPlaceholderIdentifier = (node) => {
     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]));
@@ -590,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;
@@ -602,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) {
@@ -616,7 +655,7 @@ 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;
@@ -627,11 +666,26 @@ const transformSource = (source, config) => {
         // 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) {
@@ -668,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 {};