@octanejs/mdx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @octanejs/mdx
+
+[MDX](https://mdxjs.com) for the [octane](https://github.com/octanejs/octane)
+UI framework — documentation stays in `.mdx`/`.md` and renders as **compiled octane
+components**.
+
+The split mirrors `docs/react-library-compat-plan.md` §2: **@mdx-js/mdx's
+compiler is framework-agnostic and reused verbatim** — with `jsx: true` it
+emits the compiled document as classic JSX *source*, which is exactly the
+React-style `.tsx` dialect octane's own compiler handles. The pipeline is
+
+```
+.mdx / .md  →  @mdx-js/mdx (JSX/ESM source)  →  octane/compiler  →  compiled octane module
+```
+
+— compile, don't interpret: no MDX runtime, no `_jsx` shims, the document
+becomes an ordinary octane component module (client codegen or SSR HTML-string
+codegen). Only @mdx-js/react's ~50-line provider layer is ported here.
+
+## Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { octane } from 'octane/compiler/vite'; // or @octanejs/vite-plugin
+import { octaneMdx } from '@octanejs/mdx/vite';
+
+export default defineConfig({
+	plugins: [octaneMdx(), octane()],
+});
+```
+
+`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
+auto-detection, `ssr: true|false` to force.
+
+Options: `md: false` (leave `.md` alone), `providerImportSource: null` (disable
+the provider wiring), `remarkPlugins` / `rehypePlugins` / `recmaPlugins`,
+`format`, `mdxOptions` (escape hatch). The default remark set is
+`defaultRemarkPlugins` = GFM + frontmatter + `export const frontmatter`.
+
+## Usage
+
+```mdx
+---
+title: Getting started
+---
+
+import Counter from './Counter.tsrx';
+
+# {frontmatter.title}
+
+Octane components just work: <Counter start={2} />
+```
+
+```tsrx
+import Doc, { frontmatter } from './getting-started.mdx';
+import { MDXProvider } from '@octanejs/mdx';
+
+export function Page() @{
+	<MDXProvider components={{ h1: FancyHeading, code: Snippet }}>
+		<Doc />
+	</MDXProvider>
+}
+```
+
+A mapping can also be passed per-document: `<Doc components={{ h1: FancyHeading }} />`.
+Mapping values are octane components or replacement host tag names (`{ em: 'i' }`);
+the special `wrapper` key is the document layout.
+
+## API (vs @mdx-js/react)
+
+- `MDXProvider({ components, disableParentContext, children })` — ported;
+  nested providers merge, function-form `components` receives the inherited
+  mapping.
+- `useMDXComponents(components?)` — ported, with one deliberate divergence:
+  the `useMemo` referential-stability wrapper is dropped so the call is valid
+  in BOTH runtimes (octane's client `useMemo` needs a live client render scope;
+  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).
+
+## SSR + hydration
+
+A document compiled with `mode: 'server'` renders through `octane/server`'s
+`renderToString`, and the resulting HTML **hydrates byte-for-byte** into the
+client-compiled module via `hydrateRoot` (embedded `.tsrx` components adopt
+their server DOM and stay interactive).
+
+Both mapping routes work on the server:
+
+- the `components` **prop** — `renderToString(Doc, { components })`;
+- **`MDXProvider` from `@octanejs/mdx/server`** — the same provider layer
+  mirrored onto `octane/server` context (the client and server runtimes have
+  disjoint context stores, so each side ships its own provider; server-mode
+  documents read `useMDXComponents` from `@octanejs/mdx/server`
+  automatically). A document rendered under the server provider hydrates
+  byte-for-byte into the client `MDXProvider` with the same mapping.
+
+## Syntax highlighting (Shiki)
+
+Highlighting is a rehype concern, so it hooks in through `rehypePlugins` — no
+integration code and nothing bundled (add `@shikijs/rehype` yourself):
+
+```ts
+import { octaneMdx } from '@octanejs/mdx/vite';
+import rehypeShiki from '@shikijs/rehype';
+
+octaneMdx({
+	rehypePlugins: [[rehypeShiki, { theme: 'github-light' }]],
+});
+```
+
+Shiki's hast output serializes through the same pipeline as any other content:
+highlighted tokens render on the client, serialize identically on the server,
+and hydrate cleanly (see `tests/shiki.test.ts`). Note `@shikijs/rehype` is
+async — it works in the vite plugin and `compileMdx`, not `compileMdxSync`.
+
+## Notes
+
+- Markdown-generated elements ride octane's value-position (`createElement`
+  descriptor) path — documents are static content, and embedded `.tsrx`
+  components keep their full compiled fast path.
+- `.mdx` edits fast-refresh in dev: the pipeline wraps the document's default
+  export in octane's runtime `hmr()` and self-accepts, so live mounts re-render
+  the new body in place (no page reload; the vite plugin enables this in serve
+  mode automatically).

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@octanejs/mdx",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "MDX for the octane renderer — compiles .mdx/.md through @mdx-js/mdx to JSX source and then through octane/compiler, so documents render as real compiled octane components (templates, not runtime descriptors); ships the @mdx-js/react provider layer (MDXProvider/useMDXComponents) ported onto octane context.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/mdx"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "types",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./compile": {
+      "types": "./types/compile.d.ts",
+      "default": "./src/compile.js"
+    },
+    "./vite": {
+      "types": "./types/vite.d.ts",
+      "default": "./src/vite.js"
+    }
+  },
+  "dependencies": {
+    "@jridgewell/remapping": "^2.3.5",
+    "@mdx-js/mdx": "^3.1.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "source-map": "^0.7.6",
+    "octane": "0.1.3"
+  },
+  "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.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/compile.js

@@ -0,0 +1,281 @@
+/**
+ * @octanejs/mdx — the compile pipeline (`…/compile` entry).
+ *
+ * Strategy (docs/react-library-compat-plan.md §2): @mdx-js/mdx's compiler is
+ * framework-agnostic — with `jsx: true` it emits the compiled document as
+ * CLASSIC JSX SOURCE instead of framework runtime calls. That emitted program
+ * is exactly the React-style `.tsx` dialect octane's compiler already handles,
+ * so the pipeline is
+ *
+ *   .mdx/.md → @mdx-js/mdx (JSX/ESM source) → octane/compiler → compiled octane
+ *
+ * i.e. an MDX document becomes a REAL compiled octane component module (client
+ * descriptor/template codegen, or server HTML-string codegen when
+ * `mode: 'server'`) — no MDX runtime, no interpretation. `providerImportSource`
+ * defaults to `@octanejs/mdx`, wiring `_provideComponents()` in the emitted
+ * code to this package's `useMDXComponents` (the octane port of
+ * @mdx-js/react's provider).
+ *
+ * The only adaptation between the two compilers is `recmaOctaneAdapter`, a tiny
+ * ESTree pass over MDX's output: MDX's no-layout branch CALLS
+ * `_createMdxContent(props)` directly, which bypasses octane's
+ * `(props, __s, __extra)` component ABI (the server body would run with
+ * `__s === undefined` and lean on scope-recovery). The pass rewrites the bare
+ * call to `<_createMdxContent {...props}/>` so both branches mount through the
+ * component machinery on client AND server. (The layout branch's
+ * `<_createMdxContent {...props}/>` tag needs no help: octane classifies
+ * `_`-starting identifier tags as component references, per JSX semantics.)
+ *
+ * The two former SERVER-mode fixups are gone — their octane gaps are fixed:
+ * `ssrComponent` renders a host-tag-STRING comp as a
+ * `<!--[--><tag>…</tag><!--]-->` block (the shape the client's componentSlot /
+ * de-opt host renderer adopts on hydration), and the server compiler
+ * value-lowers a returned fragment through `ssrChild([...])` exactly like the
+ * client's descriptor array — so `<_components.h1>` member tags and the
+ * document's fragment body take the SAME shape on both sides (hydration-safe).
+ *
+ * Authored in `.js` (like octane's `compiler/vite.js` and @octanejs/stylex's
+ * vite entry) so the `…/vite` plugin — which imports this module — loads when a
+ * consuming app's `vite.config.ts` pulls it in through Node's ESM loader.
+ */
+import remapping from '@jridgewell/remapping';
+import { compile as mdxCompile, compileSync as mdxCompileSync } from '@mdx-js/mdx';
+import { compile as octaneCompile } from 'octane/compiler';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
+import { SourceMapGenerator } from 'source-map';
+
+/**
+ * @typedef {object} CompileMdxResult
+ * @property {string} code
+ * @property {unknown} map
+ */
+
+/**
+ * @typedef {object} CompileMdxOptions
+ * @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 {string | null} [providerImportSource]
+ *   Module the emitted document reads the provider mapping from
+ *   (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
+ *   `'@octanejs/mdx/server'` (server), so each runtime reads ITS OWN context
+ *   store (they are disjoint; see src/server.ts). Pass `null` to disable the
+ *   provider wiring entirely (only `props.components` applies).
+ * @property {import('@mdx-js/mdx').CompileOptions['remarkPlugins']} [remarkPlugins] remark plugins. Defaults to `defaultRemarkPlugins` (GFM + frontmatter + frontmatter-export).
+ * @property {import('@mdx-js/mdx').CompileOptions['rehypePlugins']} [rehypePlugins]
+ * @property {import('@mdx-js/mdx').CompileOptions['recmaPlugins']} [recmaPlugins] Extra recma (ESTree) plugins, run before the octane adapter pass.
+ * @property {'mdx' | 'md' | 'detect'} [format] Source syntax: `'mdx'`, plain `'md'` (no JSX/ESM/expressions), or `'detect'` by file extension. Default `'detect'`.
+ * @property {Omit<import('@mdx-js/mdx').CompileOptions, 'jsx' | 'jsxRuntime' | 'jsxImportSource' | 'outputFormat' | 'providerImportSource' | 'remarkPlugins' | 'rehypePlugins' | 'recmaPlugins' | 'format' | 'SourceMapGenerator'>} [mdxOptions] Escape hatch: other @mdx-js/mdx options. The pipeline owns `jsx`/`outputFormat`/the options above.
+ */
+
+/**
+ * The default remark plugin set: GitHub-flavored markdown, YAML/TOML
+ * frontmatter parsing, and the `export const frontmatter = {…}` export.
+ * Exported so a custom `remarkPlugins` list can extend rather than replace it.
+ *
+ * @type {import('@mdx-js/mdx').CompileOptions['remarkPlugins']}
+ */
+export const defaultRemarkPlugins = [remarkGfm, remarkFrontmatter, remarkMdxFrontmatter];
+
+/**
+ * Compile MDX/markdown source to a compiled octane module (async — supports async plugins).
+ *
+ * @param {string} source
+ * @param {string} id
+ * @param {CompileMdxOptions} [options]
+ * @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);
+}
+
+/**
+ * Synchronous {@link compileMdx} (the default plugin set is fully sync).
+ *
+ * @param {string} source
+ * @param {string} id
+ * @param {CompileMdxOptions} [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);
+}
+
+/**
+ * @param {string} id
+ * @param {CompileMdxOptions} options
+ * @returns {import('@mdx-js/mdx').CompileOptions}
+ */
+function buildMdxOptions(id, options) {
+	const format =
+		options.format && options.format !== 'detect'
+			? options.format
+			: id.endsWith('.md')
+				? 'md'
+				: 'mdx';
+	const provider =
+		options.providerImportSource === undefined
+			? options.mode === 'server'
+				? '@octanejs/mdx/server'
+				: '@octanejs/mdx'
+			: options.providerImportSource;
+	return {
+		...options.mdxOptions,
+		format,
+		// The load-bearing switch: emit JSX SOURCE (no jsx-runtime calls), which
+		// octane's compiler lowers to its own codegen.
+		jsx: true,
+		// Map the intermediate JSX back to the .mdx source — stage one of the
+		// chained map octaneStage composes (stage two is octane's own map).
+		SourceMapGenerator,
+		...(provider === null ? {} : { providerImportSource: provider }),
+		remarkPlugins: options.remarkPlugins ?? defaultRemarkPlugins,
+		rehypePlugins: options.rehypePlugins,
+		recmaPlugins: [...(options.recmaPlugins ?? []), recmaOctaneAdapter],
+	};
+}
+
+/**
+ * @param {string} jsxSource
+ * @param {unknown} mdxMap
+ * @param {string} id
+ * @param {CompileMdxOptions} options
+ * @returns {CompileMdxResult}
+ */
+function octaneStage(jsxSource, mdxMap, id, options) {
+	const mode = options.mode ?? 'client';
+	const out = octaneCompile(jsxSource, id, {
+		mode,
+		hmr: mode === 'client' && !!options.hmr,
+		dev: mode === 'client' && !!options.dev,
+	});
+	// Two-stage sourcemap: octane's map targets the INTERMEDIATE JSX text;
+	// @mdx-js/mdx's map (via SourceMapGenerator) targets the original .mdx.
+	// Compose them (most-recent-first) so generated positions trace all the way
+	// back to the document. The non-empty guard is defensive: if a compile shape
+	// ever yields no overlapping segments, keep octane's intermediate map (its
+	// `sourcesContent` is the intermediate JSX — still steppable in devtools,
+	// unlike a blank map). The octane SERVER compile emits an empty-mappings map
+	// by design (SSR maps are a later octane refinement).
+	if (out.map && mdxMap) {
+		const chained = remapping([out.map, mdxMap], () => null);
+		if (String(chained.mappings).length > 0) out.map = chained;
+	}
+	// 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
+	// `hmr` flag alone leaves `.mdx` edits as full module invalidations. The
+	// PIPELINE knows the emitted shape, so it appends the exact registration the
+	// octane compiler emits for `.tsrx` exports: wrap the default export in the
+	// runtime `hmr()` (identity-stable across edits — parents keep their mounted
+	// wrapper) + a self-accepting `import.meta.hot` block that swaps the body
+	// and re-renders live blocks in place. Appending after the fact keeps the
+	// source map's earlier segments valid (ESM imports hoist).
+	if (mode === 'client' && options.hmr && /\bexport default function MDXContent\b/.test(out.code)) {
+		out.code +=
+			"\nimport { hmr as _$mdxHmr, HMR as _$mdxHMR } from 'octane';\n" +
+			'MDXContent = _$mdxHmr(MDXContent);\n' +
+			'if (import.meta.hot) {\n' +
+			'  import.meta.hot.accept((module) => {\n' +
+			'    module && MDXContent[_$mdxHMR].update(module.default);\n' +
+			'  });\n' +
+			'}\n';
+	}
+	return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// recmaOctaneAdapter — the ESTree pass described in the module doc.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MDX_BODY_NAME = '_createMdxContent';
+
+function recmaOctaneAdapter() {
+	/** @param {unknown} tree */
+	return (tree) => {
+		walkReplace(/** @type {EstreeNode} */ (tree), adaptNode);
+	};
+}
+
+/** @typedef {{ type: string, [key: string]: unknown }} EstreeNode */
+
+/**
+ * @param {unknown} value
+ * @returns {value is EstreeNode}
+ */
+function isNode(value) {
+	return value !== null && typeof value === 'object' && typeof value.type === 'string';
+}
+
+/**
+ * Visit `node` (post-decision, pre-recursion): return a replacement node to
+ * swap in (recursed into by the caller), or null to keep the node and recurse.
+ *
+ * @param {EstreeNode} node
+ * @returns {EstreeNode | null}
+ */
+function adaptNode(node) {
+	// `_createMdxContent(props)` → `<_createMdxContent {...props}/>`.
+	if (
+		node.type === 'CallExpression' &&
+		isNode(node.callee) &&
+		node.callee.type === 'Identifier' &&
+		node.callee.name === MDX_BODY_NAME &&
+		Array.isArray(node.arguments) &&
+		node.arguments.length <= 1 &&
+		(node.arguments.length === 0 || isNode(node.arguments[0]))
+	) {
+		return jsxSelfClosing(MDX_BODY_NAME, node.arguments[0] ?? null);
+	}
+	return null;
+}
+
+/**
+ * Depth-first walk that can REPLACE child nodes in place (arrays and single
+ * node-valued keys). Skips location metadata keys.
+ *
+ * @param {EstreeNode} node
+ * @param {(n: EstreeNode) => EstreeNode | null} visit
+ */
+function walkReplace(node, visit) {
+	for (const key of Object.keys(node)) {
+		if (key === 'loc' || key === 'range' || key === 'position' || key === 'data') continue;
+		const value = node[key];
+		if (Array.isArray(value)) {
+			for (let i = 0; i < value.length; i++) {
+				const child = value[i];
+				if (!isNode(child)) continue;
+				const next = visit(child);
+				if (next !== null) value[i] = next;
+				else walkReplace(child, visit);
+			}
+		} else if (isNode(value)) {
+			const next = visit(value);
+			if (next !== null) node[key] = next;
+			else walkReplace(value, visit);
+		}
+	}
+}
+
+/**
+ * @param {string} name
+ * @param {EstreeNode | null} spreadArgument
+ * @returns {EstreeNode}
+ */
+function jsxSelfClosing(name, spreadArgument) {
+	return {
+		type: 'JSXElement',
+		openingElement: {
+			type: 'JSXOpeningElement',
+			name: { type: 'JSXIdentifier', name },
+			attributes: spreadArgument ? [{ type: 'JSXSpreadAttribute', argument: spreadArgument }] : [],
+			selfClosing: true,
+		},
+		closingElement: null,
+		children: [],
+	};
+}

package/src/env.d.ts

@@ -0,0 +1,16 @@
+// @types/mdx (pulled in via @mdx-js/mdx's public types) requires a GLOBAL
+// `JSX` namespace, which octane deliberately does not declare in its runtime
+// types (JSX typing lives in the compiler's volar layer, per-`.tsrx` file).
+// Minimal ambient declarations so this package typechecks standalone — no
+// octane code reads these.
+declare namespace JSX {
+	type Element = unknown;
+
+	interface ElementClass {
+		[name: string]: unknown;
+	}
+
+	interface IntrinsicElements {
+		[name: string]: Record<string, unknown>;
+	}
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * @octanejs/mdx — the runtime provider layer.
+ *
+ * Strategy (docs/react-library-compat-plan.md §2): @mdx-js/mdx's core is
+ * framework-agnostic (the compile pipeline lives in `./compile` + `./vite`);
+ * only @mdx-js/react's thin React layer is ported here, onto octane context.
+ * `MDXProvider` / `useMDXComponents` are a port of @mdx-js/react/lib/index.js
+ * (v3): the same context, the same function-vs-object `components` merge, the
+ * same `disableParentContext` behavior.
+ *
+ * Compiled `.mdx` modules import `useMDXComponents` from here (the pipeline's
+ * default `providerImportSource`) and merge its result under `props.components`
+ * — so a components mapping can come from either the provider context or the
+ * `components` prop, exactly like MDX + React.
+ *
+ * ONE deliberate divergence from the React source: @mdx-js/react wraps the
+ * merge in `useMemo([contextComponents, components])` — a referential-stability
+ * optimization only. Octane's `useMemo` is the CLIENT runtime's (the `octane`
+ * entry has no server condition), and it requires a live render scope — a
+ * server-compiled document calls `useMDXComponents()` during `renderToString`,
+ * where the client scope is null and `useMemo` would crash. `useContext`, by
+ * contrast, is null-scope safe (it returns the context default). So the merge
+ * runs unmemoized: same observable mapping every render, valid in both
+ * runtimes (on the server the client context yields its default `{}`, and the
+ * `props.components` route still applies).
+ *
+ * SSR provider support lives in `@octanejs/mdx/server` — the same layer
+ * mirrored onto `octane/server` context (the two runtimes' context stores are
+ * disjoint; server-mode documents import `useMDXComponents` from there). Keep
+ * the merge semantics here and in src/server.ts in lockstep.
+ */
+import { createContext, createElement, useContext, type ComponentBody } from 'octane';
+
+/**
+ * A components mapping: markdown element name (`h1`, `p`, `code`, …) or
+ * embedded-component name → the octane component (or replacement host tag
+ * name) that renders it. The special `wrapper` key is the document layout.
+ */
+export interface MDXComponents {
+	[name: string]: ComponentBody<any> | string | MDXComponents;
+}
+
+/** `components` as accepted by MDXProvider/useMDXComponents: a mapping, or a function of the inherited mapping (@mdx-js/react parity). */
+export type MDXComponentsProp = MDXComponents | ((inherited: MDXComponents) => MDXComponents);
+
+// Per @mdx-js/react lib/index.js: `const emptyComponents = {}` +
+// `const MDXContext = React.createContext(emptyComponents)`.
+const emptyComponents: MDXComponents = {};
+const MDXContext = createContext<MDXComponents>(emptyComponents);
+
+/**
+ * Get the current components mapping: the provider context merged with (or
+ * mapped through) `components`. Port of @mdx-js/react's `useMDXComponents`
+ * (see the module doc for the deliberately-dropped `useMemo`).
+ *
+ * `use*`-named, so a compiled caller appends its call-site slot symbol as the
+ * trailing arg — tolerated and ignored (no hook state lives here; `useContext`
+ * is not slot-threaded in octane).
+ */
+export function useMDXComponents(
+	components?: MDXComponentsProp | null | symbol,
+	_slot?: symbol,
+): MDXComponents {
+	// The compiler-injected slot is arg 0 for the common no-`components` call
+	// (`useMDXComponents()` compiles to `useMDXComponents(SLOT)`). A symbol is
+	// never a components value — normalize it away.
+	if (typeof components === 'symbol') components = undefined;
+	const contextComponents = useContext(MDXContext);
+	// Custom merge via a function (@mdx-js/react parity).
+	if (typeof components === 'function') return components(contextComponents);
+	return { ...contextComponents, ...components };
+}
+
+export interface MDXProviderProps {
+	/** MDX content (and anything else that reads the mapping) rendered under this provider. */
+	children?: unknown;
+	/** Mapping to merge over (or function of) the inherited mapping. */
+	components?: MDXComponentsProp | null;
+	/** Ignore any parent MDXProvider and use exactly `components` (@mdx-js/react parity). */
+	disableParentContext?: boolean;
+}
+
+/**
+ * Provider of the MDX components context. Port of @mdx-js/react's
+ * `MDXProvider`: nested providers MERGE by default (`components` over the
+ * inherited mapping); `disableParentContext` starts from scratch.
+ */
+export function MDXProvider(props: MDXProviderProps): unknown {
+	let allComponents: MDXComponents;
+	if (props.disableParentContext) {
+		allComponents =
+			typeof props.components === 'function'
+				? props.components(emptyComponents)
+				: (props.components ?? emptyComponents);
+	} else {
+		allComponents = useMDXComponents(props.components);
+	}
+	return createElement(MDXContext.Provider as ComponentBody<any>, {
+		value: allComponents,
+		children: props.children,
+	});
+}
+
+/** The props every compiled MDX document component accepts. */
+export interface MDXProps {
+	/** Per-render components mapping, merged over the provider context. */
+	components?: MDXComponents;
+	[key: string]: unknown;
+}

package/src/octane-compiler.d.ts

@@ -0,0 +1,13 @@
+// `octane/compiler` is authored in JSDoc'd JS with no shipped declarations —
+// a minimal ambient surface for the one entry point this package consumes.
+declare module 'octane/compiler' {
+	export function compile(
+		source: string,
+		id: string,
+		options?: {
+			mode?: 'client' | 'server';
+			hmr?: boolean;
+			dev?: boolean;
+		},
+	): { code: string; map: unknown };
+}

package/src/server.ts

@@ -0,0 +1,65 @@
+/**
+ * @octanejs/mdx/server — the provider layer for SERVER renders.
+ *
+ * octane's client and server runtimes are separate modules with disjoint
+ * context stores, so the client `MDXProvider` (./index.ts, built on `octane`
+ * context) cannot thread a mapping through `renderToString` — its `useContext`
+ * runs null-scope on the server and yields the `{}` default. The server
+ * runtime has its own full context implementation (`scope.$$ctxValues`,
+ * top-down within one render pass), so this entry mirrors the provider layer
+ * onto `octane/server` context: same merge, same function-form `components`,
+ * same `disableParentContext` — see ./index.ts for the @mdx-js/react port
+ * notes. KEEP THE MERGE SEMANTICS IN LOCKSTEP with ./index.ts (both are the
+ * same ~40-line port; only the runtime import differs).
+ *
+ * The compile pipeline points a server-mode document's `providerImportSource`
+ * here (client mode keeps `@octanejs/mdx`), so `useMDXComponents()` inside a
+ * server-compiled document reads THIS context — and a document rendered under
+ * this `MDXProvider` serializes with the same mapping the client provider
+ * produces at hydration. Client bundles never import this module.
+ */
+import { createContext, createElement, useContext } from 'octane/server';
+import type { MDXComponents, MDXComponentsProp, MDXProviderProps } from './index.js';
+
+export type { MDXComponents, MDXComponentsProp, MDXProviderProps, MDXProps } from './index.js';
+
+const emptyComponents: MDXComponents = {};
+const MDXContext = createContext<MDXComponents>(emptyComponents);
+
+/**
+ * Server `useMDXComponents`: the provider context merged with (or mapped
+ * through) `components`. Same contract as the client export (./index.ts).
+ */
+export function useMDXComponents(
+	components?: MDXComponentsProp | null | symbol,
+	_slot?: symbol,
+): MDXComponents {
+	// Tolerate a compiler-injected trailing slot symbol, like the client export.
+	if (typeof components === 'symbol') components = undefined;
+	const contextComponents = useContext(MDXContext);
+	if (typeof components === 'function') return components(contextComponents);
+	return { ...contextComponents, ...components };
+}
+
+/**
+ * Server `MDXProvider`: provides the mapping for every document rendered
+ * below it in this `renderToString` pass. Mount shape mirrors the client
+ * provider exactly (one provider component frame + one context frame), so a
+ * document server-rendered under this provider hydrates byte-for-byte into
+ * the client `MDXProvider`.
+ */
+export function MDXProvider(props: MDXProviderProps): unknown {
+	let allComponents: MDXComponents;
+	if (props.disableParentContext) {
+		allComponents =
+			typeof props.components === 'function'
+				? props.components(emptyComponents)
+				: (props.components ?? emptyComponents);
+	} else {
+		allComponents = useMDXComponents(props.components);
+	}
+	return createElement(MDXContext.Provider as any, {
+		value: allComponents,
+		children: props.children,
+	});
+}

package/src/vite.js

@@ -0,0 +1,87 @@
+/**
+ * @octanejs/mdx — the Vite plugin (`…/vite` entry).
+ *
+ * `octaneMdx()` transforms `.mdx` (and by default `.md`) modules through the
+ * full pipeline in `./compile` — @mdx-js/mdx (JSX source) → octane/compiler —
+ * and returns FINAL JS, so it composes with `@octanejs/vite-plugin` /
+ * `octane/compiler/vite` without ordering hazards: both are `enforce: 'pre'`,
+ * but the octane plugin only claims `.tsrx`/`.tsx`/`.ts`/`.js` ids and this one
+ * only claims `.mdx`/`.md`, so the two transforms never see the same module.
+ *
+ * SSR target selection mirrors `octane/compiler/vite` exactly: an explicit
+ * `ssr` option wins; otherwise Vite's transform-level SSR flag OR the
+ * environment consumer marks a server build (`mode: 'server'` codegen), so the
+ * SAME document renders to HTML strings on the server and hydratable DOM code
+ * on the client.
+ *
+ * Authored in `.js` (like octane's `compiler/vite.js` and @octanejs/stylex's
+ * vite entry) so the plugin loads when a consuming app's `vite.config.ts`
+ * pulls it in through Node's ESM loader — which resolves the on-disk file
+ * exactly as written and never applies TS-style `.js` → `.ts` mapping.
+ */
+import { compileMdx } from './compile.js';
+
+/**
+ * @typedef {Omit<import('./compile.js').CompileMdxOptions, 'mode' | 'hmr' | 'dev'> & {
+ *   ssr?: boolean,
+ *   md?: boolean,
+ *   hmr?: boolean,
+ * }} OctaneMdxPluginOptions
+ *
+ * `ssr` forces the codegen target for EVERY module — `true` always server,
+ * `false` always client. Leave unset for per-module auto-detection (standard
+ * Vite SSR setups). Mirrors `octane/compiler/vite`'s `ssr` option.
+ * `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).
+ */
+
+/**
+ * Structural Vite plugin type — avoids a hard type dependency on vite (this
+ * package's published surface is source; see @octanejs/stylex's vite entry for
+ * the same choice).
+ *
+ * @typedef {{
+ *   name: string,
+ *   enforce: 'pre',
+ *   configResolved(config: { command: string }): void,
+ *   transform(code: string, id: string, options?: { ssr?: boolean }): Promise<{ code: string, map: unknown } | null>,
+ * }} OctaneMdxPlugin
+ */
+
+/**
+ * @param {OctaneMdxPluginOptions} [options]
+ * @returns {OctaneMdxPlugin}
+ */
+export function octaneMdx(options = {}) {
+	const { ssr: forceSsr, md, hmr, ...compileOptions } = options;
+	let hmrEnabled = hmr;
+	const includeMd = md !== false;
+	return {
+		name: 'octane-mdx',
+		enforce: 'pre',
+		configResolved(config) {
+			if (hmrEnabled === undefined) hmrEnabled = config.command === 'serve';
+		},
+		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;
+			// An ASSET-query import (`import text from './doc.md?raw'`, ?url, ?inline)
+			// is vite's territory: its asset plugin already LOADED the module as JS
+			// (`export default "…"`), so compiling here would mangle it — and the
+			// author explicitly asked for the file, not the document. Internal
+			// bookkeeping queries (?v=hash, ?used, ?import) still transform.
+			if (/(^|&)(raw|url|inline|worker|sharedworker)(=|&|$)/.test(query)) return null;
+			const ssr =
+				forceSsr !== undefined
+					? forceSsr
+					: transformOptions?.ssr === true || this.environment?.config?.consumer === 'server';
+			return compileMdx(code, file, {
+				...compileOptions,
+				mode: ssr ? 'server' : 'client',
+				hmr: !ssr && !!hmrEnabled,
+				dev: !ssr && !!hmrEnabled,
+			});
+		},
+	};
+}

package/types/compile.d.ts

@@ -0,0 +1,68 @@
+// Hand-written declarations for src/compile.js (authored in `.js` so the vite
+// entry's import chain loads under Node's native ESM loader — same convention
+// as @octanejs/vite-plugin's types/). Keep in lockstep with the implementation.
+import type { CompileOptions } from '@mdx-js/mdx';
+
+export interface CompileMdxResult {
+	code: string;
+	map: unknown;
+}
+
+export interface CompileMdxOptions {
+	/** octane codegen target: `'client'` (DOM) or `'server'` (SSR HTML strings). Default `'client'`. */
+	mode?: 'client' | 'server';
+	/** octane compiler HMR wrapping (client only; the vite plugin wires this to serve mode). */
+	hmr?: boolean;
+	/** octane compiler dev metadata (client only; same gate as `hmr`). */
+	dev?: boolean;
+	/**
+	 * Module the emitted document reads the provider mapping from
+	 * (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
+	 * `'@octanejs/mdx/server'` (server), so each runtime reads ITS OWN context
+	 * store (they are disjoint; see src/server.ts). Pass `null` to disable the
+	 * provider wiring entirely (only `props.components` applies).
+	 */
+	providerImportSource?: string | null;
+	/** remark plugins. Defaults to `defaultRemarkPlugins` (GFM + frontmatter + frontmatter-export). */
+	remarkPlugins?: CompileOptions['remarkPlugins'];
+	rehypePlugins?: CompileOptions['rehypePlugins'];
+	/** Extra recma (ESTree) plugins, run before the octane adapter pass. */
+	recmaPlugins?: CompileOptions['recmaPlugins'];
+	/** Source syntax: `'mdx'`, plain `'md'` (no JSX/ESM/expressions), or `'detect'` by file extension. Default `'detect'`. */
+	format?: 'mdx' | 'md' | 'detect';
+	/** Escape hatch: other @mdx-js/mdx options. The pipeline owns `jsx`/`outputFormat`/the options above. */
+	mdxOptions?: Omit<
+		CompileOptions,
+		| 'jsx'
+		| 'jsxRuntime'
+		| 'jsxImportSource'
+		| 'outputFormat'
+		| 'providerImportSource'
+		| 'remarkPlugins'
+		| 'rehypePlugins'
+		| 'recmaPlugins'
+		| 'format'
+		| 'SourceMapGenerator'
+	>;
+}
+
+/**
+ * The default remark plugin set: GitHub-flavored markdown, YAML/TOML
+ * frontmatter parsing, and the `export const frontmatter = {…}` export.
+ * Exported so a custom `remarkPlugins` list can extend rather than replace it.
+ */
+export declare const defaultRemarkPlugins: CompileOptions['remarkPlugins'];
+
+/** Compile MDX/markdown source to a compiled octane module (async — supports async plugins). */
+export declare function compileMdx(
+	source: string,
+	id: string,
+	options?: CompileMdxOptions,
+): Promise<CompileMdxResult>;
+
+/** Synchronous {@link compileMdx} (the default plugin set is fully sync). */
+export declare function compileMdxSync(
+	source: string,
+	id: string,
+	options?: CompileMdxOptions,
+): CompileMdxResult;

package/types/vite.d.ts

@@ -0,0 +1,35 @@
+// 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';
+
+export interface OctaneMdxPluginOptions extends Omit<CompileMdxOptions, 'mode' | 'hmr' | 'dev'> {
+	/**
+	 * Force the codegen target for EVERY module — `true` always server, `false`
+	 * always client. Leave unset for per-module auto-detection (standard Vite
+	 * SSR setups). Mirrors `octane/compiler/vite`'s `ssr` option.
+	 */
+	ssr?: boolean;
+	/** Also transform `.md` modules (plain-markdown format). Default `true`. */
+	md?: boolean;
+	/** octane HMR/dev metadata override; defaults to on in serve mode (client only). */
+	hmr?: boolean;
+}
+
+/**
+ * Structural Vite plugin type — avoids a hard type dependency on vite (see
+ * @octanejs/stylex's vite entry for the same choice).
+ */
+export interface OctaneMdxPlugin {
+	name: string;
+	enforce: 'pre';
+	configResolved(config: { command: string }): void;
+	transform(
+		this: unknown,
+		code: string,
+		id: string,
+		options?: { ssr?: boolean },
+	): Promise<{ code: string; map: unknown } | null>;
+}
+
+export declare function octaneMdx(options?: OctaneMdxPluginOptions): OctaneMdxPlugin;