@octanejs/mdx 0.1.63 → 0.1.65

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,8 +13,8 @@ pnpm add @octanejs/mdx
13
13
 
14
14
  The split mirrors `docs/react-library-compat-plan.md` §2: **@mdx-js/mdx's
15
15
  compiler is framework-agnostic and reused verbatim** — with `jsx: true` it
16
- emits the compiled document as classic JSX *source*, which is exactly the
17
- React-style `.tsx` dialect octane's own compiler handles. The pipeline is
16
+ emits JSX *source*. A small printer adapter turns the two generated document
17
+ functions into Octane templates before the Octane compiler runs. The pipeline is
18
18
 
19
19
  ```
20
20
  .mdx / .md → @mdx-js/mdx (JSX/ESM source) → octane/compiler → compiled octane module
@@ -51,7 +51,8 @@ hazards. SSR target selection matches the octane plugin: per-module
51
51
  auto-detection, `ssr: true|false` to force.
52
52
 
53
53
  Options: `md: false` (leave `.md` alone), `providerImportSource: null` (disable
54
- the provider wiring), `remarkPlugins` / `rehypePlugins` / `recmaPlugins`,
54
+ the provider wiring), `strong` (apply Octane Strong checks to the document),
55
+ `overridableTags`, `remarkPlugins` / `rehypePlugins` / `recmaPlugins`,
55
56
  `format`, `mdxOptions` (escape hatch). The default remark set is
56
57
  `defaultRemarkPlugins` = GFM + frontmatter + `export const frontmatter`.
57
58
 
@@ -84,6 +85,41 @@ A mapping can also be passed per-document: `<Doc components={{ h1: FancyHeading
84
85
  Mapping values are octane components or replacement host tag names (`{ em: 'i' }`);
85
86
  the special `wrapper` key is the document layout.
86
87
 
88
+ The client and server providers are authored as Strong `.tsrx` templates. Both
89
+ generated document functions also compile as templates. Authored JavaScript
90
+ expressions and exported components retain their normal Octane semantics.
91
+
92
+ ### Static hosts and Strong mode
93
+
94
+ By default, every markdown-generated tag can be overridden through a provider
95
+ or the document's `components` prop. For a site with a fixed set of overrides,
96
+ list those tags at build time:
97
+
98
+ ```ts
99
+ octaneMdx({
100
+ strong: true,
101
+ overridableTags: ['table', 'pre'],
102
+ });
103
+ ```
104
+
105
+ All other generated tags become static host templates, including Shiki's many
106
+ highlighting spans. Overrides for omitted tags are ignored in both provider
107
+ and document mappings. An empty list makes every generated host static;
108
+ omitting the option retains full MDX override support. This does not restrict
109
+ named components, authored JSX, or the special `wrapper` layout mapping.
110
+ Provider mappings still merge before document props, and an explicit exported
111
+ layout still takes precedence over `wrapper`.
112
+
113
+ Keeping every tag overridable requires a component slot for each generated
114
+ host. For heavily highlighted documents this can increase generated code size;
115
+ use a fixed override list when the application only replaces a few tags.
116
+
117
+ Pass the application's shared Strong setting to `octaneMdx` as well as its
118
+ Octane plugin. Strong checks apply to the whole MDX module, including authored
119
+ expressions; enabling them can reject code accepted in compatibility mode.
120
+ The default remains compatibility mode. Use the same options for client and
121
+ server compilation so their hydration structure agrees.
122
+
87
123
  ## API (vs @mdx-js/react)
88
124
 
89
125
  - `MDXProvider({ components, disableParentContext, children })` — ported;
@@ -102,9 +138,9 @@ the special `wrapper` key is the document layout.
102
138
  ## SSR + hydration
103
139
 
104
140
  A document compiled with `mode: 'server'` renders through `octane/server`'s
105
- `renderToString`, and the resulting HTML **hydrates byte-for-byte** into the
106
- client-compiled module via `hydrateRoot` (embedded `.tsrx` components adopt
107
- their server DOM and stay interactive).
141
+ `renderToString`, and `hydrateRoot` adopts the resulting elements and text
142
+ into the client-compiled module. Embedded `.tsrx` components retain their
143
+ server DOM and stay interactive; internal comment anchors may change.
108
144
 
109
145
  Both mapping routes work on the server:
110
146
 
@@ -114,7 +150,7 @@ Both mapping routes work on the server:
114
150
  disjoint context stores, so each side ships its own provider; server-mode
115
151
  documents read `useMDXComponents` from `@octanejs/mdx/server`
116
152
  automatically). A document rendered under the server provider hydrates
117
- byte-for-byte into the client `MDXProvider` with the same mapping.
153
+ by adopting its DOM into the client `MDXProvider` with the same mapping.
118
154
 
119
155
  ## Syntax highlighting (Shiki)
120
156
 
@@ -137,11 +173,15 @@ async — it works in the vite plugin and `compileMdx`, not `compileMdxSync`.
137
173
 
138
174
  ## Notes
139
175
 
140
- - Markdown-generated elements ride octane's value-position (`createElement`
141
- descriptor) path — documents are static content, and embedded `.tsrx`
142
- components keep their full compiled fast path.
143
- - `.mdx` edits fast-refresh in dev: the pipeline wraps the document's default
144
- export in octane's runtime `hmr()` and self-accepts, so live mounts re-render
176
+ - Markdown-generated document functions use templates. Dynamic host overrides
177
+ still need runtime component slots; `overridableTags` lets fixed sites avoid
178
+ those slots for hosts they never override. This does not promise that arbitrary
179
+ authored expressions or imported components are descriptor-free.
180
+ - Mapped components receive ordinary Octane template children: render them
181
+ with `{children}` rather than inspecting or cloning nested element
182
+ descriptors. A single literal text child remains a string.
183
+ - `.mdx` edits fast-refresh in dev through Octane's template HMR support,
184
+ so live mounts re-render
145
185
  the new body in place (no page reload; the vite plugin enables this in serve
146
186
  mode automatically). Importers keep the named exports they read, such as
147
187
  `frontmatter`, so the update also reaches them when one is no longer
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@octanejs/mdx",
3
- "version": "0.1.63",
3
+ "version": "0.1.65",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "engines": {
@@ -26,17 +26,23 @@
26
26
  "url": "git+https://github.com/octanejs/octane.git",
27
27
  "directory": "packages/mdx"
28
28
  },
29
- "main": "src/index.ts",
30
- "module": "src/index.ts",
31
- "types": "src/index.ts",
29
+ "main": "src/index.tsrx",
30
+ "module": "src/index.tsrx",
31
+ "types": "src/index.tsrx.d.ts",
32
32
  "files": [
33
33
  "src",
34
34
  "types",
35
35
  "README.md"
36
36
  ],
37
37
  "exports": {
38
- ".": "./src/index.ts",
39
- "./server": "./src/server.ts",
38
+ ".": {
39
+ "types": "./src/index.tsrx.d.ts",
40
+ "default": "./src/index.tsrx"
41
+ },
42
+ "./server": {
43
+ "types": "./src/server.tsrx.d.ts",
44
+ "default": "./src/server.tsrx"
45
+ },
40
46
  "./compile": {
41
47
  "types": "./types/compile.d.ts",
42
48
  "default": "./src/compile.js"
@@ -61,7 +67,7 @@
61
67
  "devDependencies": {
62
68
  "@octanejs/testing-library": "0.1.63",
63
69
  "@shikijs/rehype": "^3.23.0",
64
- "octane": "0.13.2",
70
+ "octane": "0.13.7",
65
71
  "vite": "^8.1.5",
66
72
  "vitest": "^4.1.10"
67
73
  },
package/src/compile.js CHANGED
@@ -16,23 +16,12 @@
16
16
  * code to this package's `useMDXComponents` (the octane port of
17
17
  * @mdx-js/react's provider).
18
18
  *
19
- * The only adaptation between the two compilers is `recmaOctaneAdapter`, a tiny
20
- * ESTree pass over MDX's output: MDX's no-layout branch CALLS
21
- * `_createMdxContent(props)` directly, which bypasses octane's
22
- * `(props, __s, __extra)` component ABI (the server body would run with
23
- * `__s === undefined` and lean on scope-recovery). The pass rewrites the bare
24
- * call to `<_createMdxContent {...props}/>` so both branches mount through the
25
- * component machinery on client AND server. (The layout branch's
26
- * `<_createMdxContent {...props}/>` tag needs no help: octane classifies
27
- * `_`-starting identifier tags as component references, per JSX semantics.)
28
- *
29
- * The two former SERVER-mode fixups are gone — their octane gaps are fixed:
30
- * `ssrComponent` renders a host-tag-STRING comp as a
31
- * `<!--[--><tag>…</tag><!--]-->` block (the shape the client's componentSlot /
32
- * de-opt host renderer adopts on hydration), and the server compiler
33
- * value-lowers a returned fragment through `ssrChild([...])` exactly like the
34
- * client's descriptor array — so `<_components.h1>` member tags and the
35
- * document's fragment body take the SAME shape on both sides (hydration-safe).
19
+ * The final recma pass emits both generated document functions as TSRX
20
+ * templates. MDX's existing printer handles their JSX, JavaScript and source
21
+ * locations; a small body handler supplies `@{}` and template control flow.
22
+ * Both layout branches render the document body through a component boundary.
23
+ * Optional `overridableTags` specializes generated hosts without changing
24
+ * authored JSX, named components, or the provider/prop/layout merge rules.
36
25
  *
37
26
  * Authored in `.js` (like octane's `compiler/vite.js` and @octanejs/stylex's
38
27
  * vite entry) so the `…/vite` plugin — which imports this module — loads when a
@@ -94,6 +83,8 @@ import { SourceMapGenerator } from 'source-map';
94
83
  * @property {boolean} [hmr] octane compiler HMR wrapping (client only; the vite plugin wires this to serve mode).
95
84
  * @property {boolean} [dev] octane compiler dev metadata (client only; same gate as `hmr`).
96
85
  * @property {boolean} [profile] octane compiler profiling metadata (client only).
86
+ * @property {boolean} [strong] Apply Octane Strong diagnostics to the document.
87
+ * @property {readonly string[]} [overridableTags] Generated host tags that may be replaced through component mappings. Omit to keep every generated host overridable; an empty list makes all generated hosts native. Named components and layouts remain overridable.
97
88
  * @property {string | null} [providerImportSource]
98
89
  * Module the emitted document reads the provider mapping from
99
90
  * (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
@@ -195,7 +186,7 @@ function buildMdxOptions(id, options, diagnosticContext) {
195
186
  seedAuthoredJsxAttributeLocations(diagnosticContext),
196
187
  ...(options.recmaPlugins ?? []),
197
188
  restoreAuthoredJsxAttributeLocations(diagnosticContext),
198
- recmaOctaneAdapter,
189
+ [recmaOctaneAdapter, { overridableTags: options.overridableTags }],
199
190
  ],
200
191
  };
201
192
  }
@@ -367,12 +358,53 @@ function octaneStage(mdxFile, authoredSource, id, options, diagnosticContext) {
367
358
  const jsxSource = String(mdxFile.value);
368
359
  const mdxMap = mdxFile.map;
369
360
  const mode = options.mode ?? 'client';
370
- const out = octaneCompile(jsxSource, id, {
371
- mode,
372
- hmr: mode === 'client' && !!options.hmr,
373
- dev: mode === 'client' && !!options.dev,
374
- profile: mode === 'client' && !!options.profile,
375
- });
361
+ let out;
362
+ try {
363
+ out = octaneCompile(jsxSource, id, {
364
+ mode,
365
+ hmr: mode === 'client' && !!options.hmr,
366
+ dev: mode === 'client' && !!options.dev,
367
+ profile: mode === 'client' && !!options.profile,
368
+ strong: options.strong,
369
+ });
370
+ } catch (error) {
371
+ if (
372
+ mdxMap &&
373
+ typeof error?.loc?.line === 'number' &&
374
+ typeof error.loc.column === 'number' &&
375
+ typeof error.pos === 'number'
376
+ ) {
377
+ const trace = new TraceMap(JSON.parse(JSON.stringify(mdxMap)));
378
+ const starts = sourceLineStarts(authoredSource);
379
+ const start = mapDiagnosticPosition(
380
+ trace,
381
+ authoredSource,
382
+ starts,
383
+ error.loc,
384
+ GREATEST_LOWER_BOUND,
385
+ );
386
+ const end =
387
+ typeof error.end === 'number'
388
+ ? mapDiagnosticPosition(
389
+ trace,
390
+ authoredSource,
391
+ starts,
392
+ positionForOffset(jsxSource, sourceLineStarts(jsxSource), error.end),
393
+ LEAST_UPPER_BOUND,
394
+ )
395
+ : null;
396
+ if (start !== null) {
397
+ const prefix = `${id}:${error.loc.line}:${error.loc.column + 1}: `;
398
+ if (error.message.startsWith(prefix)) {
399
+ error.message = `${id}:${start.line}:${start.column + 1}: ${error.message.slice(prefix.length)}`;
400
+ }
401
+ error.loc = { line: start.line, column: start.column };
402
+ error.pos = start.offset;
403
+ error.end = Math.max(start.offset, end?.offset ?? start.offset);
404
+ }
405
+ }
406
+ throw error;
407
+ }
376
408
  // Two-stage sourcemap: octane's map targets the INTERMEDIATE JSX text;
377
409
  // @mdx-js/mdx's map (via SourceMapGenerator) targets the original .mdx.
378
410
  // Compose them (most-recent-first) so generated positions trace all the way
@@ -398,51 +430,10 @@ function octaneStage(mdxFile, authoredSource, id, options, diagnosticContext) {
398
430
  id,
399
431
  diagnosticContext.authoredAttributes,
400
432
  );
401
- // Fast refresh for documents: octane's compiler only auto-wraps EXPORTED
402
- // `@{}`-form components in `hmr(...)` — `MDXContent` (a passthrough function
403
- // returning a ternary of descriptors) isn't recognized as one, so the octane
404
- // `hmr` flag alone leaves `.mdx` edits as full module invalidations. The
405
- // PIPELINE knows the emitted shape, so it appends the registration the
406
- // octane compiler emits for `.tsrx` exports: wrap the default export in the
407
- // runtime `hmr()`, hand each evaluation's body to the wrapper that importers
408
- // and live blocks already hold (kept in `hot.data`, so parents never remount
409
- // the document), and self-accept. Importers keep the bindings they linked
410
- // against, so the callback invalidates when another export they read
411
- // changed or cannot be compared. Appending after the fact keeps the source
412
- // map's earlier segments valid (ESM imports hoist).
413
- if (mode === 'client' && options.hmr && /\bexport default function MDXContent\b/.test(out.code)) {
414
- const namedExports = mdxFile.data.octaneNamedExports;
415
- const changed =
416
- namedExports === null
417
- ? '_$mdxModule'
418
- : `_$mdxModule && (${[['default', 'MDXContent'], ...namedExports]
419
- .map(([name, local]) => `_$mdxModule[${JSON.stringify(name)}] !== ${local}`)
420
- .join(' || ')})`;
421
- out.code +=
422
- "\nimport { hmr as _$mdxHmr, HMR as _$mdxHMR } from 'octane';\n" +
423
- 'MDXContent = _$mdxHmr(MDXContent);\n' +
424
- 'if (import.meta.hot) {\n' +
425
- ' const _$mdxPrevious = import.meta.hot.data?.__octaneMdxContent;\n' +
426
- ' if (_$mdxPrevious) {\n' +
427
- ' if (_$mdxPrevious[_$mdxHMR].update(MDXContent)) MDXContent = _$mdxPrevious;\n' +
428
- ' else import.meta.hot.invalidate();\n' +
429
- ' }\n' +
430
- ' if (import.meta.hot.data) import.meta.hot.data.__octaneMdxContent = MDXContent;\n' +
431
- ' import.meta.hot.accept((_$mdxModule) => {\n' +
432
- ` if (${changed}) import.meta.hot.invalidate();\n` +
433
- ' });\n' +
434
- '}\n';
435
- }
436
- // Register the final public binding after the MDX-specific HMR wrapper. The
437
- // core compiler may also recognize the generated dispatcher, but its location
438
- // belongs to intermediate JSX and its registration precedes this wrapper. This
439
- // document-level registration deliberately overrides both with the authored
440
- // `.mdx` identity and stable line-one location.
441
- if (
442
- mode === 'client' &&
443
- options.profile &&
444
- /\bexport default function MDXContent\b/.test(out.code)
445
- ) {
433
+ // Core owns template HMR, including named-export invalidation. Register the
434
+ // final public binding with the authored document identity instead of its
435
+ // generated function location. Appending preserves earlier source-map segments.
436
+ if (mode === 'client' && options.profile && mdxFile.data.octaneDocumentTemplate) {
446
437
  const metadata = {
447
438
  id: `${id}#MDXContent@1:0`,
448
439
  name: 'MDXContent',
@@ -623,42 +614,154 @@ function remapDiagnostics(diagnostics, mdxMap, jsxSource, source, id, authoredAt
623
614
 
624
615
  const MDX_BODY_NAME = '_createMdxContent';
625
616
 
626
- function recmaOctaneAdapter() {
627
- /**
628
- * @param {unknown} tree
629
- * @param {{ data: Record<string, unknown> }} file
630
- */
631
- return (tree, file) => {
632
- walkReplace(/** @type {EstreeNode} */ (tree), adaptNode);
633
- file.data.octaneNamedExports = namedExportBindings(/** @type {any} */ (tree));
617
+ /** @param {{ overridableTags?: readonly string[] }} options */
618
+ function recmaOctaneAdapter({ overridableTags }) {
619
+ if (
620
+ overridableTags !== undefined &&
621
+ (!Array.isArray(overridableTags) ||
622
+ overridableTags.some((tag) => typeof tag !== 'string' || !/^[a-z][\w:.-]*$/.test(tag)))
623
+ ) {
624
+ throw new TypeError('overridableTags must be an array of host tag names.');
625
+ }
626
+ const allowed = overridableTags === undefined ? null : new Set(overridableTags);
627
+ // recma-stringify and recma-jsx already share this printer extension point.
628
+ // Keep their JSX handlers and source-map writer; only our synthetic body
629
+ // needs syntax that ESTree's ordinary JavaScript printer does not know.
630
+ const settings = this.data('settings') ?? {};
631
+ this.data('settings', {
632
+ ...settings,
633
+ handlers: { ...settings.handlers, OctaneTemplateBody: printTemplateBody },
634
+ });
635
+ return (tree, file) => ({
636
+ ...tree,
637
+ body: tree.body.map((statement) => {
638
+ const fn = statement.type === 'ExportDefaultDeclaration' ? statement.declaration : statement;
639
+ if (
640
+ fn.type !== 'FunctionDeclaration' ||
641
+ (fn.id?.name !== MDX_BODY_NAME && fn.id?.name !== 'MDXContent')
642
+ )
643
+ return statement;
644
+ const body = adaptGeneratedHosts(fn.body, allowed);
645
+ const last = body.body.at(-1);
646
+ if (last?.type !== 'ReturnStatement') return statement;
647
+ const next = {
648
+ ...fn,
649
+ body: {
650
+ type: 'OctaneTemplateBody',
651
+ setup: body.body.slice(0, -1),
652
+ output: mapNodes(last.argument, adaptNode),
653
+ },
654
+ };
655
+ if (statement.type === 'ExportDefaultDeclaration') {
656
+ file.data.octaneDocumentTemplate = true;
657
+ return { ...statement, declaration: next };
658
+ }
659
+ return next;
660
+ }),
661
+ });
662
+ }
663
+
664
+ function printTemplateBody(node, state) {
665
+ state.write('@{\n');
666
+ for (const statement of node.setup) {
667
+ this[statement.type](statement, state);
668
+ state.write('\n');
669
+ }
670
+ const output = (expression) => {
671
+ if (expression.type === 'ConditionalExpression') {
672
+ state.write('<>@if (');
673
+ this[expression.test.type](expression.test, state);
674
+ state.write(') {\n');
675
+ output(expression.consequent);
676
+ state.write('\n} @else {\n');
677
+ output(expression.alternate);
678
+ state.write('\n}</>');
679
+ } else if (expression.type === 'JSXElement' || expression.type === 'JSXFragment') {
680
+ this[expression.type](expression, state);
681
+ } else {
682
+ state.write('<>{');
683
+ this[expression.type](expression, state);
684
+ state.write('}</>');
685
+ }
634
686
  };
687
+ output(node.output);
688
+ state.write('\n}');
635
689
  }
636
690
 
637
691
  /**
638
- * The document's named exports as [exportName, localName] pairs, or null when
639
- * one has no single module binding to compare: a re-export, `export *`, or a
640
- * destructuring declaration.
641
- *
642
- * @param {{ body: any[] }} program
643
- * @returns {Array<[string, string]> | null}
692
+ * Only MDX-generated host references have defaults in this local map. Explicit
693
+ * JSX is deliberately outside the mapping contract, even when its spelling
694
+ * happens to match a generated reference. Non-identifier tags use MDX aliases.
644
695
  */
645
- function namedExportBindings(program) {
646
- /** @type {Array<[string, string]>} */
647
- const bindings = [];
648
- for (const node of program.body) {
649
- if (node.type === 'ExportAllDeclaration') return null;
650
- if (node.type !== 'ExportNamedDeclaration') continue;
651
- if (node.source) return null;
652
- const declaration = node.declaration;
653
- for (const { id } of declaration?.declarations ?? (declaration ? [declaration] : [])) {
654
- if (id.type !== 'Identifier') return null;
655
- bindings.push([id.name, id.name]);
656
- }
657
- for (const specifier of node.specifiers) {
658
- bindings.push([specifier.exported.name ?? specifier.exported.value, specifier.local.name]);
696
+ function adaptGeneratedHosts(body, allowed) {
697
+ const tags = new Set();
698
+ const aliases = new Map();
699
+ for (const statement of body.body) {
700
+ for (const declaration of statement.declarations ?? []) {
701
+ if (declaration.id.name === '_components' && declaration.init?.type === 'ObjectExpression') {
702
+ for (const property of declaration.init.properties) {
703
+ const name = property.key?.name ?? property.key?.value;
704
+ if (property.type === 'Property' && property.value?.value === name) tags.add(name);
705
+ }
706
+ }
707
+ if (
708
+ declaration.init?.type === 'MemberExpression' &&
709
+ declaration.init.object.name === '_components'
710
+ ) {
711
+ aliases.set(
712
+ declaration.id.name,
713
+ declaration.init.property.name ?? declaration.init.property.value,
714
+ );
715
+ }
659
716
  }
660
717
  }
661
- return bindings;
718
+ if (tags.size === 0) return body;
719
+ return mapNodes(body, (node) => {
720
+ if (node.type !== 'JSXElement' || node.data?._mdxExplicitJsx) return null;
721
+ const name = node.openingElement.name;
722
+ const tag =
723
+ name.type === 'JSXMemberExpression' && name.object.name === '_components'
724
+ ? name.property.name
725
+ : name.type === 'JSXIdentifier'
726
+ ? aliases.get(name.name)
727
+ : undefined;
728
+ if (!tags.has(tag)) return null;
729
+ if (allowed !== null && !allowed.has(tag)) {
730
+ const nativeName = { ...name, type: 'JSXIdentifier', name: tag };
731
+ return {
732
+ ...node,
733
+ openingElement: { ...node.openingElement, name: nativeName },
734
+ closingElement: node.closingElement ? { ...node.closingElement, name: nativeName } : null,
735
+ };
736
+ }
737
+ const child = node.children.length === 1 ? node.children[0] : null;
738
+ if (
739
+ child?.type !== 'JSXExpressionContainer' ||
740
+ child.expression.type !== 'Literal' ||
741
+ typeof child.expression.value !== 'string'
742
+ )
743
+ return null;
744
+ // MDX's single string child is already a scalar value. Keep it a prop
745
+ // instead of allocating a template body for every highlighted token.
746
+ // Appending matches nested JSX children winning over attribute spreads.
747
+ return {
748
+ ...node,
749
+ openingElement: {
750
+ ...node.openingElement,
751
+ selfClosing: true,
752
+ attributes: [
753
+ ...node.openingElement.attributes,
754
+ {
755
+ type: 'JSXAttribute',
756
+ name: { type: 'JSXIdentifier', name: 'children' },
757
+ value: child,
758
+ },
759
+ ],
760
+ },
761
+ closingElement: null,
762
+ children: [],
763
+ };
764
+ });
662
765
  }
663
766
 
664
767
  /** @typedef {{ type: string, [key: string]: unknown }} EstreeNode */
@@ -694,31 +797,24 @@ function adaptNode(node) {
694
797
  return null;
695
798
  }
696
799
 
697
- /**
698
- * Depth-first walk that can REPLACE child nodes in place (arrays and single
699
- * node-valued keys). Skips location metadata keys.
700
- *
701
- * @param {EstreeNode} node
702
- * @param {(n: EstreeNode) => EstreeNode | null} visit
703
- */
704
- function walkReplace(node, visit) {
705
- for (const key of Object.keys(node)) {
800
+ /** Copy-on-write traversal; upstream and custom recma ASTs remain untouched. */
801
+ function mapNodes(node, visit) {
802
+ if (!isNode(node)) return node;
803
+ let result = visit(node) ?? node;
804
+ for (const key of Object.keys(result)) {
706
805
  if (key === 'loc' || key === 'range' || key === 'position' || key === 'data') continue;
707
- const value = node[key];
708
- if (Array.isArray(value)) {
709
- for (let i = 0; i < value.length; i++) {
710
- const child = value[i];
711
- if (!isNode(child)) continue;
712
- const next = visit(child);
713
- if (next !== null) value[i] = next;
714
- else walkReplace(child, visit);
715
- }
716
- } else if (isNode(value)) {
717
- const next = visit(value);
718
- if (next !== null) node[key] = next;
719
- else walkReplace(value, visit);
806
+ const value = result[key];
807
+ const next = Array.isArray(value)
808
+ ? value.map((child) => mapNodes(child, visit))
809
+ : mapNodes(value, visit);
810
+ if (
811
+ Array.isArray(value) ? next.some((child, index) => child !== value[index]) : next !== value
812
+ ) {
813
+ if (result === node) result = { ...node };
814
+ result[key] = next;
720
815
  }
721
816
  }
817
+ return result;
722
818
  }
723
819
 
724
820
  /**
@@ -1,3 +1,5 @@
1
+ 'use strong';
2
+
1
3
  /**
2
4
  * @octanejs/mdx — the runtime provider layer.
3
5
  *
@@ -27,9 +29,9 @@
27
29
  * SSR provider support lives in `@octanejs/mdx/server` — the same layer
28
30
  * mirrored onto `octane/server` context (the two runtimes' context stores are
29
31
  * disjoint; server-mode documents import `useMDXComponents` from there). Keep
30
- * the merge semantics here and in src/server.ts in lockstep.
32
+ * the merge semantics here and in src/server.tsrx in lockstep.
31
33
  */
32
- import { createContext, createElement, useContext, type ComponentBody } from 'octane';
34
+ import { createContext, useContext, type ComponentBody } from 'octane';
33
35
 
34
36
  /**
35
37
  * A components mapping: markdown element name (`h1`, `p`, `code`, …) or
@@ -85,7 +87,7 @@ export interface MDXProviderProps {
85
87
  * `MDXProvider`: nested providers MERGE by default (`components` over the
86
88
  * inherited mapping); `disableParentContext` starts from scratch.
87
89
  */
88
- export function MDXProvider(props: MDXProviderProps): unknown {
90
+ export function MDXProvider(props: MDXProviderProps) @{
89
91
  let allComponents: MDXComponents;
90
92
  if (props.disableParentContext) {
91
93
  allComponents =
@@ -95,10 +97,7 @@ export function MDXProvider(props: MDXProviderProps): unknown {
95
97
  } else {
96
98
  allComponents = useMDXComponents(props.components);
97
99
  }
98
- return createElement(MDXContext as ComponentBody<any>, {
99
- value: allComponents,
100
- children: props.children,
101
- });
100
+ <MDXContext value={allComponents} children={props.children} />
102
101
  }
103
102
 
104
103
  /** The props every compiled MDX document component accepts. */
@@ -0,0 +1,25 @@
1
+ import type { ComponentBody } from 'octane';
2
+
3
+ export interface MDXComponents {
4
+ [name: string]: ComponentBody<any> | string | MDXComponents;
5
+ }
6
+
7
+ export type MDXComponentsProp = MDXComponents | ((inherited: MDXComponents) => MDXComponents);
8
+
9
+ export interface MDXProviderProps {
10
+ children?: unknown;
11
+ components?: MDXComponentsProp | null;
12
+ disableParentContext?: boolean;
13
+ }
14
+
15
+ export interface MDXProps {
16
+ components?: MDXComponents;
17
+ [key: string]: unknown;
18
+ }
19
+
20
+ export declare function useMDXComponents(
21
+ components?: MDXComponentsProp | null | symbol,
22
+ _slot?: symbol,
23
+ ): MDXComponents;
24
+
25
+ export declare function MDXProvider(props: MDXProviderProps): unknown;
@@ -1,15 +1,17 @@
1
+ 'use strong';
2
+
1
3
  /**
2
4
  * @octanejs/mdx/server — the provider layer for SERVER renders.
3
5
  *
4
6
  * octane's client and server runtimes are separate modules with disjoint
5
- * context stores, so the client `MDXProvider` (./index.ts, built on `octane`
7
+ * context stores, so the client `MDXProvider` (./index.tsrx, built on `octane`
6
8
  * context) cannot thread a mapping through `renderToString` — its `useContext`
7
9
  * runs null-scope on the server and yields the `{}` default. The server
8
10
  * runtime has its own full context implementation (`scope.$$ctxValues`,
9
11
  * top-down within one render pass), so this entry mirrors the provider layer
10
12
  * onto `octane/server` context: same merge, same function-form `components`,
11
- * same `disableParentContext` — see ./index.ts for the @mdx-js/react port
12
- * notes. KEEP THE MERGE SEMANTICS IN LOCKSTEP with ./index.ts (both are the
13
+ * same `disableParentContext` — see ./index.tsrx for the @mdx-js/react port
14
+ * notes. KEEP THE MERGE SEMANTICS IN LOCKSTEP with ./index.tsrx (both are the
13
15
  * same ~40-line port; only the runtime import differs).
14
16
  *
15
17
  * The compile pipeline points a server-mode document's `providerImportSource`
@@ -18,17 +20,17 @@
18
20
  * this `MDXProvider` serializes with the same mapping the client provider
19
21
  * produces at hydration. Client bundles never import this module.
20
22
  */
21
- import { createContext, createElement, useContext } from 'octane/server';
22
- import type { MDXComponents, MDXComponentsProp, MDXProviderProps } from './index.js';
23
+ import { createContext, useContext } from 'octane/server';
24
+ import type { MDXComponents, MDXComponentsProp, MDXProviderProps } from './index.tsrx';
23
25
 
24
- export type { MDXComponents, MDXComponentsProp, MDXProviderProps, MDXProps } from './index.js';
26
+ export type { MDXComponents, MDXComponentsProp, MDXProviderProps, MDXProps } from './index.tsrx';
25
27
 
26
28
  const emptyComponents: MDXComponents = {};
27
29
  const MDXContext = createContext<MDXComponents>(emptyComponents);
28
30
 
29
31
  /**
30
32
  * Server `useMDXComponents`: the provider context merged with (or mapped
31
- * through) `components`. Same contract as the client export (./index.ts).
33
+ * through) `components`. Same contract as the client export (./index.tsrx).
32
34
  */
33
35
  export function useMDXComponents(
34
36
  components?: MDXComponentsProp | null | symbol,
@@ -48,7 +50,7 @@ export function useMDXComponents(
48
50
  * document server-rendered under this provider hydrates byte-for-byte into
49
51
  * the client `MDXProvider`.
50
52
  */
51
- export function MDXProvider(props: MDXProviderProps): unknown {
53
+ export function MDXProvider(props: MDXProviderProps) @{
52
54
  let allComponents: MDXComponents;
53
55
  if (props.disableParentContext) {
54
56
  allComponents =
@@ -58,8 +60,5 @@ export function MDXProvider(props: MDXProviderProps): unknown {
58
60
  } else {
59
61
  allComponents = useMDXComponents(props.components);
60
62
  }
61
- return createElement(MDXContext as any, {
62
- value: allComponents,
63
- children: props.children,
64
- });
63
+ <MDXContext value={allComponents} children={props.children} />
65
64
  }
@@ -0,0 +1 @@
1
+ export * from '@octanejs/mdx';
@@ -1,7 +1,12 @@
1
1
  // Hand-written declarations for src/compile.js (authored in `.js` so the vite
2
2
  // entry's import chain loads under Node's native ESM loader — same convention
3
3
  // as @octanejs/vite-plugin's types/). Keep in lockstep with the implementation.
4
- import type { CompileOptions } from '@mdx-js/mdx';
4
+ // This exported compile-only entry avoids the root's evaluation types, which
5
+ // require a global JSX namespace. Keep the upstream options without that global.
6
+ import type { createFormatAwareProcessors } from '@mdx-js/mdx/internal-create-format-aware-processors';
7
+
8
+ type CompilerInput = NonNullable<Parameters<typeof createFormatAwareProcessors>[0]>;
9
+ type CompileOptions = { -readonly [K in keyof CompilerInput]: CompilerInput[K] };
5
10
 
6
11
  export interface CompileMdxResult {
7
12
  code: string;
@@ -38,11 +43,19 @@ export interface CompileMdxOptions {
38
43
  dev?: boolean;
39
44
  /** octane compiler profiling metadata (client only). */
40
45
  profile?: boolean;
46
+ /** Apply Octane Strong diagnostics to the generated document and authored JavaScript. */
47
+ strong?: boolean;
48
+ /**
49
+ * Generated host tags that may be replaced through component mappings.
50
+ * Omit to keep every generated host overridable; [] makes them all native.
51
+ * Named components and layouts retain their existing mapping behavior.
52
+ */
53
+ overridableTags?: readonly string[];
41
54
  /**
42
55
  * Module the emitted document reads the provider mapping from
43
56
  * (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
44
57
  * `'@octanejs/mdx/server'` (server), so each runtime reads ITS OWN context
45
- * store (they are disjoint; see src/server.ts). Pass `null` to disable the
58
+ * store (they are disjoint; see src/server.tsrx). Pass `null` to disable the
46
59
  * provider wiring entirely (only `props.components` applies).
47
60
  */
48
61
  providerImportSource?: string | null;
package/src/env.d.ts DELETED
@@ -1,16 +0,0 @@
1
- // @types/mdx (pulled in via @mdx-js/mdx's public types) requires a GLOBAL
2
- // `JSX` namespace, which octane deliberately does not declare in its runtime
3
- // types (JSX typing lives in the compiler's volar layer, per-`.tsrx` file).
4
- // Minimal ambient declarations so this package typechecks standalone — no
5
- // octane code reads these.
6
- declare namespace JSX {
7
- type Element = unknown;
8
-
9
- interface ElementClass {
10
- [name: string]: unknown;
11
- }
12
-
13
- interface IntrinsicElements {
14
- [name: string]: Record<string, unknown>;
15
- }
16
- }