@octanejs/mdx 0.1.3 → 0.1.7

package/README.md

@@ -30,6 +30,14 @@ export default defineConfig({
 });
 ```
 
+Pass `profile: true` to both plugins for a browser profiling build:
+
+```ts
+plugins: [octaneMdx({ profile: true }), octane({ profile: true })];
+```
+
+Profiling metadata is never emitted by the MDX server transform.
+
 `octaneMdx()` claims `.mdx`/`.md` and produces final JS, so it composes with the
 octane plugin (which claims `.tsrx`/`.tsx`/`.ts`/`.js`) without ordering
 hazards. SSR target selection matches the octane plugin: per-module
@@ -80,7 +88,9 @@ the special `wrapper` key is the document layout.
   SSR passes call this during `renderToString`). Same observable mapping.
 - `@octanejs/mdx/compile` — `compileMdx` / `compileMdxSync` /
   `defaultRemarkPlugins`, the plugin's pipeline as a library (used by the SSR
-  tests, usable for static-site tooling).
+  tests, usable for static-site tooling). Results include nonfatal compiler
+  `diagnostics`; JSX warning ranges are mapped back to the authored `.mdx`
+  document. The Vite plugin publishes the same warnings during transforms.
 
 ## SSR + hydration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/mdx",
-  "version": "0.1.3",
+  "version": "0.1.7",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -48,6 +48,7 @@
   },
   "dependencies": {
     "@jridgewell/remapping": "^2.3.5",
+    "@jridgewell/trace-mapping": "^0.3.31",
     "@mdx-js/mdx": "^3.1.1",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
@@ -55,15 +56,14 @@
     "source-map": "^0.7.6"
   },
   "peerDependencies": {
-    "octane": "0.1.6"
+    "octane": "0.1.10"
   },
   "devDependencies": {
-    "@jridgewell/trace-mapping": "^0.3.31",
     "@shikijs/rehype": "^3.0.0",
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
-    "@octanejs/testing-library": "0.1.3",
-    "octane": "0.1.6"
+    "@octanejs/testing-library": "0.1.7",
+    "octane": "0.1.10"
   },
   "scripts": {
     "test": "vitest run"

package/src/compile.js

@@ -39,8 +39,14 @@
  * consuming app's `vite.config.ts` pulls it in through Node's ESM loader.
  */
 import remapping from '@jridgewell/remapping';
+import {
+	TraceMap,
+	originalPositionFor,
+	GREATEST_LOWER_BOUND,
+	LEAST_UPPER_BOUND,
+} from '@jridgewell/trace-mapping';
 import { compile as mdxCompile, compileSync as mdxCompileSync } from '@mdx-js/mdx';
-import { compile as octaneCompile } from 'octane/compiler';
+import { __analyzeNativeChangeDiagnostics, compile as octaneCompile } from 'octane/compiler';
 import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
@@ -50,6 +56,36 @@ import { SourceMapGenerator } from 'source-map';
  * @typedef {object} CompileMdxResult
  * @property {string} code
  * @property {unknown} map
+ * @property {Array<{
+ *   code: string,
+ *   severity: 'warning',
+ *   message: string,
+ *   filename: string,
+ *   start: { offset: number, line: number, column: number },
+ *   end: { offset: number, line: number, column: number },
+ *   suggestions: Array<{
+ *     start: { offset: number, line: number, column: number },
+ *     end: { offset: number, line: number, column: number },
+ *     attribute: 'onInput' | 'onInputCapture',
+ *   }>,
+ * }>} diagnostics
+ */
+
+/**
+ * @typedef {object} AuthoredJsxAttributeLocation
+ * @property {string} name
+ * @property {number} start
+ * @property {number} end
+ * @property {{ start: { line: number, column: number }, end: { line: number, column: number } }} loc
+ * @property {boolean} staticallyWarned
+ */
+
+/**
+ * @typedef {object} DiagnosticMappingContext
+ * @property {AuthoredJsxAttributeLocation[]} authoredAttributes
+ * @property {WeakMap<object, AuthoredJsxAttributeLocation>} attributeLocations
+ * @property {string} source
+ * @property {string} id
  */
 
 /**
@@ -57,6 +93,7 @@ import { SourceMapGenerator } from 'source-map';
  * @property {'client' | 'server'} [mode] octane codegen target: `'client'` (DOM) or `'server'` (SSR HTML strings). Default `'client'`.
  * @property {boolean} [hmr] octane compiler HMR wrapping (client only; the vite plugin wires this to serve mode).
  * @property {boolean} [dev] octane compiler dev metadata (client only; same gate as `hmr`).
+ * @property {boolean} [profile] octane compiler profiling metadata (client only).
  * @property {string | null} [providerImportSource]
  *   Module the emitted document reads the provider mapping from
  *   (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
@@ -88,8 +125,17 @@ export const defaultRemarkPlugins = [remarkGfm, remarkFrontmatter, remarkMdxFron
  * @returns {Promise<CompileMdxResult>}
  */
 export async function compileMdx(source, id, options = {}) {
-	const out = await mdxCompile({ value: source, path: id }, buildMdxOptions(id, options));
-	return octaneStage(String(out.value), out.map, id, options);
+	const diagnosticContext = {
+		authoredAttributes: [],
+		attributeLocations: new WeakMap(),
+		source,
+		id,
+	};
+	const out = await mdxCompile(
+		{ value: source, path: id },
+		buildMdxOptions(id, options, diagnosticContext),
+	);
+	return octaneStage(String(out.value), out.map, source, id, options, diagnosticContext);
 }
 
 /**
@@ -101,16 +147,26 @@ export async function compileMdx(source, id, options = {}) {
  * @returns {CompileMdxResult}
  */
 export function compileMdxSync(source, id, options = {}) {
-	const out = mdxCompileSync({ value: source, path: id }, buildMdxOptions(id, options));
-	return octaneStage(String(out.value), out.map, id, options);
+	const diagnosticContext = {
+		authoredAttributes: [],
+		attributeLocations: new WeakMap(),
+		source,
+		id,
+	};
+	const out = mdxCompileSync(
+		{ value: source, path: id },
+		buildMdxOptions(id, options, diagnosticContext),
+	);
+	return octaneStage(String(out.value), out.map, source, id, options, diagnosticContext);
 }
 
 /**
  * @param {string} id
  * @param {CompileMdxOptions} options
+ * @param {DiagnosticMappingContext} diagnosticContext
  * @returns {import('@mdx-js/mdx').CompileOptions}
  */
-function buildMdxOptions(id, options) {
+function buildMdxOptions(id, options, diagnosticContext) {
 	const format =
 		options.format && options.format !== 'detect'
 			? options.format
@@ -135,23 +191,186 @@ function buildMdxOptions(id, options) {
 		...(provider === null ? {} : { providerImportSource: provider }),
 		remarkPlugins: options.remarkPlugins ?? defaultRemarkPlugins,
 		rehypePlugins: options.rehypePlugins,
-		recmaPlugins: [...(options.recmaPlugins ?? []), recmaOctaneAdapter],
+		recmaPlugins: [
+			seedAuthoredJsxAttributeLocations(diagnosticContext),
+			...(options.recmaPlugins ?? []),
+			restoreAuthoredJsxAttributeLocations(diagnosticContext),
+			recmaOctaneAdapter,
+		],
+	};
+}
+
+/**
+ * @param {unknown} tree
+ * @param {(attribute: Record<string, any>) => void} callback
+ */
+function visitJsxAttributes(tree, callback) {
+	const activeObjects = new WeakSet();
+	/** @param {unknown} value */
+	function visit(value) {
+		if (value === null || typeof value !== 'object' || activeObjects.has(value)) return;
+		activeObjects.add(value);
+		const node = /** @type {Record<string, any>} */ (value);
+		if (node.type === 'JSXAttribute') callback(node);
+		for (const [key, child] of Object.entries(node)) {
+			if (key === 'loc' || key === 'range' || key === 'position') continue;
+			if (Array.isArray(child)) child.forEach(visit);
+			else visit(child);
+		}
+		activeObjects.delete(value);
+	}
+	visit(tree);
+}
+
+/**
+ * @param {Record<string, any>} node
+ * @param {AuthoredJsxAttributeLocation} location
+ */
+function applyNodeLocation(node, location) {
+	node.start = location.start;
+	node.end = location.end;
+	node.range = [location.start, location.end];
+	node.loc = {
+		start: { ...location.loc.start },
+		end: { ...location.loc.end },
+	};
+}
+
+/**
+ * Add the exact source location missing from MDX's JSXIdentifier attribute
+ * names. Remark and rehype transforms have already established stage-one
+ * source provenance here; the parent JSXAttribute carries that location, and
+ * seeding the child makes the map point directly at the token the Octane
+ * diagnostic covers. Analyze this pre-recma tree once as well: a later
+ * transform may preserve or copy source locations, but only attributes that
+ * were already statically warned at this boundary may receive an authored fix.
+ *
+ * @param {DiagnosticMappingContext} context
+ */
+function seedAuthoredJsxAttributeLocations(context) {
+	return function recmaSeedAuthoredJsxAttributeLocations() {
+		/** @param {unknown} tree */
+		return (tree) => {
+			context.authoredAttributes.length = 0;
+			const occurrences = [];
+			visitJsxAttributes(tree, (attribute) => occurrences.push(attribute));
+			const occurrenceCounts = new Map();
+			for (const attribute of occurrences) {
+				occurrenceCounts.set(attribute, (occurrenceCounts.get(attribute) ?? 0) + 1);
+			}
+			for (const attribute of occurrences) {
+				if (occurrenceCounts.get(attribute) !== 1) continue;
+				const name = attribute.name;
+				if (
+					name?.type !== 'JSXIdentifier' ||
+					typeof name.name !== 'string' ||
+					typeof attribute.start !== 'number' ||
+					typeof attribute.loc?.start?.line !== 'number' ||
+					typeof attribute.loc?.start?.column !== 'number'
+				)
+					continue;
+				const location = {
+					name: name.name,
+					start: attribute.start,
+					end: attribute.start + name.name.length,
+					loc: {
+						start: {
+							line: attribute.loc.start.line,
+							column: attribute.loc.start.column,
+						},
+						end: {
+							line: attribute.loc.start.line,
+							column: attribute.loc.start.column + name.name.length,
+						},
+					},
+					staticallyWarned: false,
+				};
+				context.authoredAttributes.push(location);
+				context.attributeLocations.set(attribute, location);
+				const seededName = { ...name };
+				attribute.name = seededName;
+				applyNodeLocation(seededName, location);
+			}
+			const warningRanges = new Set(
+				__analyzeNativeChangeDiagnostics(tree, context.source, context.id).diagnostics.flatMap(
+					(diagnostic) =>
+						diagnostic.suggestions.map(
+							(suggestion) => `${suggestion.start.offset}:${suggestion.end.offset}`,
+						),
+				),
+			);
+			for (const location of context.authoredAttributes) {
+				location.staticallyWarned = warningRanges.has(`${location.start}:${location.end}`);
+			}
+		};
+	};
+}
+
+/**
+ * Restore exact locations on unchanged attribute identities after user recma
+ * transforms. Classification was frozen before those transforms, so even a
+ * later plugin that copies a location cannot turn a previously-safe authored
+ * callback into an actionable replacement.
+ *
+ * @param {DiagnosticMappingContext} context
+ */
+function restoreAuthoredJsxAttributeLocations(context) {
+	return function recmaRestoreAuthoredJsxAttributeLocations() {
+		/** @param {unknown} tree */
+		return (tree) => {
+			const occurrences = [];
+			visitJsxAttributes(tree, (attribute) => occurrences.push(attribute));
+			const occurrenceCounts = new Map();
+			for (const attribute of occurrences) {
+				occurrenceCounts.set(attribute, (occurrenceCounts.get(attribute) ?? 0) + 1);
+			}
+			for (const attribute of occurrences) {
+				const name = attribute.name;
+				const location = context.attributeLocations.get(attribute);
+				if (
+					location &&
+					occurrenceCounts.get(attribute) === 1 &&
+					name?.type === 'JSXIdentifier' &&
+					name.name === location.name
+				) {
+					// Isolate the authored name from shallow attribute clones. Otherwise a
+					// generated clone can share this child object and regain its location
+					// when the original attribute is restored later in the traversal.
+					const restoredName = { ...name };
+					attribute.name = restoredName;
+					applyNodeLocation(restoredName, location);
+					continue;
+				}
+				// Do not let a plugin-created clone carrying copied positions masquerade
+				// as the one authored attribute captured before user transforms.
+				for (const node of [attribute, name]) {
+					if (node === null || typeof node !== 'object') continue;
+					delete node.start;
+					delete node.end;
+					delete node.range;
+					delete node.loc;
+				}
+			}
+		};
 	};
 }
 
 /**
  * @param {string} jsxSource
  * @param {unknown} mdxMap
+ * @param {string} authoredSource
  * @param {string} id
  * @param {CompileMdxOptions} options
+ * @param {DiagnosticMappingContext} diagnosticContext
  * @returns {CompileMdxResult}
  */
-function octaneStage(jsxSource, mdxMap, id, options) {
+function octaneStage(jsxSource, mdxMap, authoredSource, id, options, diagnosticContext) {
 	const mode = options.mode ?? 'client';
 	const out = octaneCompile(jsxSource, id, {
 		mode,
 		hmr: mode === 'client' && !!options.hmr,
 		dev: mode === 'client' && !!options.dev,
+		profile: mode === 'client' && !!options.profile,
 	});
 	// Two-stage sourcemap: octane's map targets the INTERMEDIATE JSX text;
 	// @mdx-js/mdx's map (via SourceMapGenerator) targets the original .mdx.
@@ -165,6 +384,19 @@ function octaneStage(jsxSource, mdxMap, id, options) {
 		const chained = remapping([out.map, mdxMap], () => null);
 		if (String(chained.mappings).length > 0) out.map = chained;
 	}
+	// Compiler diagnostics are reported against the intermediate JSX emitted by
+	// MDX. Trace every available range through stage one's source map so direct
+	// callers and Vite warnings point at the JSX the author actually wrote in the
+	// document. Markdown generated by headings/lists has no authored event prop,
+	// so native-change warnings are expected to map only from literal MDX JSX.
+	out.diagnostics = remapDiagnostics(
+		out.diagnostics,
+		mdxMap,
+		jsxSource,
+		authoredSource,
+		id,
+		diagnosticContext.authoredAttributes,
+	);
 	// Fast refresh for documents: octane's compiler only auto-wraps EXPORTED
 	// `@{}`-form components in `hmr(...)` — `MDXContent` (a passthrough function
 	// returning a ternary of descriptors) isn't recognized as one, so the octane
@@ -185,9 +417,190 @@ function octaneStage(jsxSource, mdxMap, id, options) {
 			'  });\n' +
 			'}\n';
 	}
+	// Register the final public binding after the MDX-specific HMR wrapper. The
+	// core compiler may also recognize the generated dispatcher, but its location
+	// belongs to intermediate JSX and its registration precedes this wrapper. This
+	// document-level registration deliberately overrides both with the authored
+	// `.mdx` identity and stable line-one location.
+	if (
+		mode === 'client' &&
+		options.profile &&
+		/\bexport default function MDXContent\b/.test(out.code)
+	) {
+		const metadata = {
+			id: `${id}#MDXContent@1:0`,
+			name: 'MDXContent',
+			file: id,
+			line: 1,
+			column: 0,
+			kind: 'component',
+		};
+		out.code +=
+			"\nimport { __profileComponent as _$mdxProfile } from 'octane/profiling';\n" +
+			`_$mdxProfile(MDXContent, ${JSON.stringify(metadata)});\n`;
+	}
 	return out;
 }
 
+/** @param {string} source */
+function sourceLineStarts(source) {
+	const starts = [0];
+	for (let index = 0; index < source.length; index++) {
+		if (source.charCodeAt(index) === 10) starts.push(index + 1);
+	}
+	return starts;
+}
+
+/**
+ * @param {string} source
+ * @param {number[]} starts
+ * @param {number} offset
+ */
+function positionForOffset(source, starts, offset) {
+	const clamped = Math.max(0, Math.min(source.length, offset));
+	let low = 0;
+	let high = starts.length;
+	while (low + 1 < high) {
+		const mid = (low + high) >> 1;
+		if (starts[mid] <= clamped) low = mid;
+		else high = mid;
+	}
+	return { offset: clamped, line: low + 1, column: clamped - starts[low] };
+}
+
+/**
+ * @param {TraceMap} trace
+ * @param {string} source
+ * @param {number[]} starts
+ * @param {{ offset: number, line: number, column: number }} position
+ * @param {number} bias
+ */
+function mapDiagnosticPosition(trace, source, starts, position, bias) {
+	const mapped = originalPositionFor(trace, {
+		line: position.line,
+		column: position.column,
+		bias,
+	});
+	if (mapped.line == null || mapped.column == null) return null;
+	const lineStart = starts[mapped.line - 1];
+	if (lineStart === undefined) return null;
+	return positionForOffset(source, starts, lineStart + mapped.column);
+}
+
+/**
+ * Match an Octane diagnostic to an exact authored JSX attribute source-map
+ * segment. Both source-map biases must resolve to the same seeded token: when
+ * they differ, the generated position sits between mappings and belongs to
+ * transformed/generated code rather than an authored attribute.
+ *
+ * @param {TraceMap} trace
+ * @param {string} jsxSource
+ * @param {string} source
+ * @param {number[]} starts
+ * @param {{ start: { offset: number, line: number, column: number }, end: { offset: number, line: number, column: number } }} range
+ * @param {AuthoredJsxAttributeLocation[]} authoredAttributes
+ * @returns {AuthoredJsxAttributeLocation | null}
+ */
+function exactAuthoredAttributeForDiagnostic(
+	trace,
+	jsxSource,
+	source,
+	starts,
+	range,
+	authoredAttributes,
+) {
+	const name = jsxSource.slice(range.start.offset, range.end.offset);
+	if (name.length === 0) return null;
+	const lower = mapDiagnosticPosition(trace, source, starts, range.start, GREATEST_LOWER_BOUND);
+	const upper = mapDiagnosticPosition(trace, source, starts, range.start, LEAST_UPPER_BOUND);
+	if (lower === null || upper === null || lower.offset !== upper.offset) return null;
+	return (
+		authoredAttributes.find(
+			(attribute) =>
+				attribute.staticallyWarned && attribute.name === name && attribute.start === lower.offset,
+		) ?? null
+	);
+}
+
+/**
+ * @param {string} source
+ * @param {number[]} starts
+ * @param {AuthoredJsxAttributeLocation} attribute
+ */
+function rangeForAuthoredAttribute(source, starts, attribute) {
+	return {
+		start: positionForOffset(source, starts, attribute.start),
+		end: positionForOffset(source, starts, attribute.end),
+	};
+}
+
+/**
+ * @param {CompileMdxResult['diagnostics'] | undefined} diagnostics
+ * @param {unknown} mdxMap
+ * @param {string} jsxSource
+ * @param {string} source
+ * @param {string} id
+ * @param {AuthoredJsxAttributeLocation[]} authoredAttributes
+ * @returns {CompileMdxResult['diagnostics']}
+ */
+function remapDiagnostics(diagnostics, mdxMap, jsxSource, source, id, authoredAttributes) {
+	if (!Array.isArray(diagnostics) || diagnostics.length === 0) return [];
+	const starts = sourceLineStarts(source);
+	const fileStart = positionForOffset(source, starts, 0);
+	const trace = mdxMap ? new TraceMap(JSON.parse(JSON.stringify(mdxMap))) : null;
+	const claimedAttributes = new Set();
+	return diagnostics.map((diagnostic) => {
+		const attribute = trace
+			? exactAuthoredAttributeForDiagnostic(
+					trace,
+					jsxSource,
+					source,
+					starts,
+					diagnostic,
+					authoredAttributes,
+				)
+			: null;
+		const key = attribute ? `${attribute.name}:${attribute.start}:${attribute.end}` : null;
+		if (attribute === null || key === null || claimedAttributes.has(key)) {
+			return {
+				...diagnostic,
+				filename: id,
+				start: fileStart,
+				end: fileStart,
+				suggestions: [],
+			};
+		}
+		claimedAttributes.add(key);
+		const range = rangeForAuthoredAttribute(source, starts, attribute);
+		const claimedSuggestions = new Set();
+		return {
+			...diagnostic,
+			filename: id,
+			...range,
+			suggestions: diagnostic.suggestions.flatMap((suggestion) => {
+				const suggestionAttribute = exactAuthoredAttributeForDiagnostic(
+					trace,
+					jsxSource,
+					source,
+					starts,
+					suggestion,
+					authoredAttributes,
+				);
+				if (suggestionAttribute === null) return [];
+				const suggestionKey = `${suggestionAttribute.name}:${suggestionAttribute.start}:${suggestionAttribute.end}`;
+				if (claimedSuggestions.has(suggestionKey)) return [];
+				claimedSuggestions.add(suggestionKey);
+				return [
+					{
+						...suggestion,
+						...rangeForAuthoredAttribute(source, starts, suggestionAttribute),
+					},
+				];
+			}),
+		};
+	});
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // recmaOctaneAdapter — the ESTree pass described in the module doc.
 // ─────────────────────────────────────────────────────────────────────────────

package/src/octane-compiler.d.ts

@@ -1,6 +1,24 @@
 // `octane/compiler` is authored in JSDoc'd JS with no shipped declarations —
-// a minimal ambient surface for the one entry point this package consumes.
+// a minimal ambient surface for the entry points this package consumes.
 declare module 'octane/compiler' {
+	export interface CompileDiagnosticPosition {
+		offset: number;
+		line: number;
+		column: number;
+	}
+	export interface CompileDiagnostic {
+		code: string;
+		severity: 'warning';
+		message: string;
+		filename: string;
+		start: CompileDiagnosticPosition;
+		end: CompileDiagnosticPosition;
+		suggestions: Array<{
+			start: CompileDiagnosticPosition;
+			end: CompileDiagnosticPosition;
+			attribute: 'onInput' | 'onInputCapture';
+		}>;
+	}
 	export function compile(
 		source: string,
 		id: string,
@@ -8,6 +26,12 @@ declare module 'octane/compiler' {
 			mode?: 'client' | 'server';
 			hmr?: boolean;
 			dev?: boolean;
+			profile?: boolean;
 		},
-	): { code: string; map: unknown };
+	): { code: string; map: unknown; diagnostics: CompileDiagnostic[] };
+	export function __analyzeNativeChangeDiagnostics(
+		ast: unknown,
+		source: string,
+		filename: string,
+	): { diagnostics: CompileDiagnostic[]; classifications: Map<number, string> };
 }

package/src/vite.js

@@ -20,12 +20,14 @@
  * exactly as written and never applies TS-style `.js` → `.ts` mapping.
  */
 import { compileMdx } from './compile.js';
+import { createOctaneCompiler } from 'octane/compiler/bundler';
 
 /**
  * @typedef {Omit<import('./compile.js').CompileMdxOptions, 'mode' | 'hmr' | 'dev'> & {
  *   ssr?: boolean,
  *   md?: boolean,
  *   hmr?: boolean,
+ *   profile?: boolean,
  * }} OctaneMdxPluginOptions
  *
  * `ssr` forces the codegen target for EVERY module — `true` always server,
@@ -34,6 +36,7 @@ import { compileMdx } from './compile.js';
  * `md` also transforms `.md` modules (plain-markdown format). Default `true`.
  * `hmr` is the octane HMR/dev metadata override; defaults to on in serve mode
  * (client only).
+ * `profile` enables profiling metadata in client modules only.
  */
 
 /**
@@ -44,8 +47,9 @@ import { compileMdx } from './compile.js';
  * @typedef {{
  *   name: string,
  *   enforce: 'pre',
- *   configResolved(config: { command: string }): void,
- *   transform(code: string, id: string, options?: { ssr?: boolean }): Promise<{ code: string, map: unknown } | null>,
+ *   configResolved(config: { command: string, root?: string }): void,
+ *   watchChange(id: string): void,
+ *   transform(this: { addWatchFile?(id: string): void, warn?(warning: { code: string, message: string, id: string, loc: { file: string, line: number, column: number } }): void, environment?: { config?: { consumer?: string } } }, code: string, id: string, options?: { ssr?: boolean }): Promise<import('./compile.js').CompileMdxResult | null>,
  * }} OctaneMdxPlugin
  */
 
@@ -54,15 +58,24 @@ import { compileMdx } from './compile.js';
  * @returns {OctaneMdxPlugin}
  */
 export function octaneMdx(options = {}) {
-	const { ssr: forceSsr, md, hmr, ...compileOptions } = options;
+	const { ssr: forceSsr, md, hmr, profile, ...compileOptions } = options;
 	let hmrEnabled = hmr;
+	let projectRoot = process.cwd();
+	let profileIds = createOctaneCompiler({ root: projectRoot });
+	const warnedByFile = new Map();
 	const includeMd = md !== false;
 	return {
 		name: 'octane-mdx',
 		enforce: 'pre',
 		configResolved(config) {
+			projectRoot = config.root ?? projectRoot;
+			profileIds = createOctaneCompiler({ root: projectRoot });
 			if (hmrEnabled === undefined) hmrEnabled = config.command === 'serve';
 		},
+		watchChange(id) {
+			profileIds.invalidate(id);
+			warnedByFile.delete(id.split('?')[0]);
+		},
 		async transform(code, id, transformOptions) {
 			const [file, query = ''] = id.split('?'); // Vite ids carry ?v=/?used/?raw/… suffixes
 			if (!(file.endsWith('.mdx') || (includeMd && file.endsWith('.md')))) return null;
@@ -76,12 +89,43 @@ export function octaneMdx(options = {}) {
 				forceSsr !== undefined
 					? forceSsr
 					: transformOptions?.ssr === true || this.environment?.config?.consumer === 'server';
-			return compileMdx(code, file, {
+			const profiling = !ssr && profile === true;
+			// Preserve the historical filename (and therefore output/source maps) in
+			// ordinary and server builds. Profile metadata needs the portable ID, so
+			// only the explicit client profiling specialization canonicalizes it.
+			const profileIdentity = profiling ? profileIds.resolveProfileModuleId(file) : null;
+			for (const dependency of profileIdentity?.dependencies ?? []) {
+				this.addWatchFile?.(dependency);
+			}
+			const compilerId = profileIdentity?.id ?? file;
+			const result = await compileMdx(code, compilerId, {
 				...compileOptions,
 				mode: ssr ? 'server' : 'client',
 				hmr: !ssr && !!hmrEnabled,
 				dev: !ssr && !!hmrEnabled,
+				profile: profiling,
 			});
+			let warned = warnedByFile.get(file);
+			if (warned === undefined) {
+				warned = new Set();
+				warnedByFile.set(file, warned);
+			}
+			for (const diagnostic of result.diagnostics) {
+				const key = `${diagnostic.code}:${diagnostic.start.offset}:${diagnostic.end.offset}:${diagnostic.message}`;
+				if (warned.has(key)) continue;
+				warned.add(key);
+				this.warn?.({
+					code: diagnostic.code,
+					message: diagnostic.message,
+					id: diagnostic.filename,
+					loc: {
+						file: diagnostic.filename,
+						line: diagnostic.start.line,
+						column: diagnostic.start.column,
+					},
+				});
+			}
+			return result;
 		},
 	};
 }

package/types/compile.d.ts

@@ -6,6 +6,27 @@ import type { CompileOptions } from '@mdx-js/mdx';
 export interface CompileMdxResult {
 	code: string;
 	map: unknown;
+	diagnostics: CompileMdxDiagnostic[];
+}
+
+export interface CompileMdxDiagnosticPosition {
+	offset: number;
+	line: number;
+	column: number;
+}
+
+export interface CompileMdxDiagnostic {
+	code: string;
+	severity: 'warning';
+	message: string;
+	filename: string;
+	start: CompileMdxDiagnosticPosition;
+	end: CompileMdxDiagnosticPosition;
+	suggestions: Array<{
+		start: CompileMdxDiagnosticPosition;
+		end: CompileMdxDiagnosticPosition;
+		attribute: 'onInput' | 'onInputCapture';
+	}>;
 }
 
 export interface CompileMdxOptions {
@@ -15,6 +36,8 @@ export interface CompileMdxOptions {
 	hmr?: boolean;
 	/** octane compiler dev metadata (client only; same gate as `hmr`). */
 	dev?: boolean;
+	/** octane compiler profiling metadata (client only). */
+	profile?: boolean;
 	/**
 	 * Module the emitted document reads the provider mapping from
 	 * (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /

package/types/vite.d.ts

@@ -1,7 +1,7 @@
 // Hand-written declarations for src/vite.js (authored in `.js` so it loads
 // from a consumer's vite.config.ts under Node's native ESM loader — same
 // convention as @octanejs/vite-plugin's types/). Keep in lockstep.
-import type { CompileMdxOptions } from './compile.js';
+import type { CompileMdxOptions, CompileMdxResult } from './compile.js';
 
 export interface OctaneMdxPluginOptions extends Omit<CompileMdxOptions, 'mode' | 'hmr' | 'dev'> {
 	/**
@@ -14,6 +14,8 @@ export interface OctaneMdxPluginOptions extends Omit<CompileMdxOptions, 'mode' |
 	md?: boolean;
 	/** octane HMR/dev metadata override; defaults to on in serve mode (client only). */
 	hmr?: boolean;
+	/** Enable component profiling metadata in client modules. */
+	profile?: boolean;
 }
 
 /**
@@ -23,13 +25,23 @@ export interface OctaneMdxPluginOptions extends Omit<CompileMdxOptions, 'mode' |
 export interface OctaneMdxPlugin {
 	name: string;
 	enforce: 'pre';
-	configResolved(config: { command: string }): void;
+	configResolved(config: { command: string; root?: string }): void;
+	watchChange(id: string): void;
 	transform(
-		this: unknown,
+		this: {
+			addWatchFile?(id: string): void;
+			warn?(warning: {
+				code: string;
+				message: string;
+				id: string;
+				loc: { file: string; line: number; column: number };
+			}): void;
+			environment?: { config?: { consumer?: string } };
+		},
 		code: string,
 		id: string,
 		options?: { ssr?: boolean },
-	): Promise<{ code: string; map: unknown } | null>;
+	): Promise<CompileMdxResult | null>;
 }
 
 export declare function octaneMdx(options?: OctaneMdxPluginOptions): OctaneMdxPlugin;