@octanejs/markdown 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Espen Hovlandsdal
+
+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,33 @@
+# @octanejs/markdown
+
+Octane bindings for [`react-markdown@10.1.0`](https://github.com/remarkjs/react-markdown). The default export and the `MarkdownAsync`, `MarkdownHooks`, and `defaultUrlTransform` named exports preserve the upstream processing and option contracts while producing Octane output.
+
+```tsrx
+import Markdown from '@octanejs/markdown';
+import remarkGfm from 'remark-gfm';
+
+export function Article() {
+	return (
+		<Markdown
+			remarkPlugins={[remarkGfm]}
+			components={{
+				strong({ children, node: _node, ...props }) {
+					return <strong class="highlight" {...props}>{children}</strong>;
+				},
+			}}
+		>
+			{'# Hello\n\nThis is **Octane**.'}
+		</Markdown>
+	);
+}
+```
+
+Migrate by replacing the `react-markdown` dependency and import root with `@octanejs/markdown`, then apply the ordinary React-to-Octane syntax and type conversion. Plugin values and tuples, component keys and callback props, filtering options, URL transforms, and the sync/async/hooks API shapes remain unchanged.
+
+Author `Markdown` in React-style value position (`return <Markdown>{markdown}</Markdown>`) so its static or expression child remains an inspectable Markdown value. Template-position children compile to an opaque render block and are rejected rather than invoked without their runtime scope. In a template body, pass the source explicitly with `<Markdown children={markdown} />`.
+
+## Security
+
+Raw HTML is rendered as text by default. Adding `rehype-raw` parses raw HTML but does not sanitize it. Unified plugins and component mappings execute as trusted code, and a custom URL transform can broaden the protocols accepted by the default transform. When Markdown is untrusted, add a sanitizer explicitly at the correct point in the rehype pipeline and audit any plugins, components, and URL transform used with it.
+
+See [UPSTREAM.md](./UPSTREAM.md) for the pinned source, artifact, test, and license provenance.

package/UPSTREAM.md

@@ -0,0 +1,74 @@
+# react-markdown upstream contract
+
+## Immutable pin
+
+| Field | Value |
+| --- | --- |
+| Package | `react-markdown` |
+| Version | `10.1.0` |
+| Supported range | exactly `10.1.0` |
+| Canonical repository | `remarkjs/react-markdown` |
+| Canonical commit | `44d2e4a44b37461ab7778d6870c1a9eb36393ad2` |
+| npm tarball SHA-256 | `205f5c607c68e1e42b8d7a036326bdb3a105ae55e6469ecfcaf998004609d5f7` |
+| Runtime oracle | `react@19.0.0` / `react-dom@19.0.0` |
+| Type oracle | `@types/react@19.2.17` / `@types/react-dom@19.2.3` |
+| License | MIT, retained byte-exact under both evidence boundaries |
+
+`upstream/npm/package/` is the unpacked registry artifact. `upstream/source/`
+contains the canonical runtime source, test suite, JSX loader, TypeScript
+configuration, package metadata, and license from the pinned commit. The npm
+artifact does not publish `test.jsx` or `script/load-jsx.js`, so the canonical
+repository supplies that test boundary. The runtime source and license present
+in both artifacts are byte-identical.
+
+Run `pnpm --dir packages/markdown upstream:verify`. The verifier locks all
+16 vendored files, package identity and license, the public API, and all 87
+`test.jsx` registrations. Its negative controls must reject source drift,
+license drift, a renamed upstream test, a removed inventory row, and a missing
+runtime export.
+
+## Runtime and type export crosswalk
+
+| Upstream export | Octane disposition | Evidence |
+| --- | --- | --- |
+| default `Markdown` | Ported to `src/index.ts` | `tests/conformance/public-types.test.ts`, `tests/conformance/sync.server.test.ts`, `typetests/public-api.test-d.ts` |
+| `MarkdownAsync` | Ported to `src/markdown-async.ts`; sync-render divergence recorded as `react-markdown-async-sync-render` | `tests/async/markdown-async.server.test.ts`, `typetests/public-api.test-d.ts` |
+| `MarkdownHooks` | Ported to `src/markdown-hooks.tsrx` | `tests/hooks/markdown-hooks.test.ts`, `typetests/public-api.test-d.ts` |
+| `defaultUrlTransform` | Ported source-near to `src/url-transform.ts` | `tests/differential/url-transform.test.ts`, `typetests/public-api.test-d.ts` |
+| `AllowElement` | Ported React-free to `src/types.ts` | `typetests/public-api.test-d.ts` |
+| `Components` | Ported with Octane intrinsic/component mappings to `src/types.ts` | `typetests/public-api.test-d.ts`, `tests/differential/processor.test.ts` |
+| `ExtraProps` | Ported React-free to `src/types.ts` | `typetests/public-api.test-d.ts` |
+| `HooksOptions` | Ported with `OctaneNode` fallback to `src/types.ts` | `typetests/public-api.test-d.ts`, `tests/hooks/markdown-hooks.test.ts` |
+| `Options` | Ported React-free to `src/types.ts` | `typetests/public-api.test-d.ts`, `tests/validation.test.ts` |
+| `UrlTransform` | Ported React-free to `src/types.ts` | `typetests/public-api.test-d.ts`, `tests/differential/url-transform.test.ts` |
+
+`audit/public-api.json` is the machine-readable boundary and export crosswalk.
+`status.json` agrees that the complete root runtime and public type surface is
+ported.
+
+## Test boundary
+
+The canonical `test.jsx` contains 87 nested `t.test` registrations. They are
+frozen individually in `audit/test-inventory.json`. The pristine lane executes
+that vendored file byte-for-byte with its vendored JSX loader, Node test,
+React/ReactDOM 19.0.0, and the upstream-declared test dependencies. The 87-entry
+`audit/adapted-case-crosswalk.json` binds every pinned source-line identity to a
+concrete adapted test identity and integrity-locks its assertion source.
+
+Every port-authored test under `tests/` has exactly one disposition in
+`audit/test-classifications.json`. Repo-authored type probes live under
+`audit/type-probes/` and `typetests/` and are locked by `audit/type-parity.json`
+with assertion-group inventories and mutation controls.
+
+## Architecture and adoption evidence
+
+`tests/probes/async-component.*` proves the load-bearing server contract: a
+mapped component typed to return `OctaneNode | Promise<OctaneNode>` is invoked
+through an element descriptor, awaited by `prerender`, preserves nested
+children, and propagates rejection.
+
+`tests/adoption/` freezes canonical examples from the pinned documentation and
+an Apache-2.0 public application consumer. Its migration ledger separates
+ordinary React-to-Octane edits from changes specific to this package. Those
+files are classified as Octane-only framework contracts, not React-parity
+evidence.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@octanejs/markdown",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "react-markdown 10.1.0 bindings for Octane",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/markdown"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@types/hast": "^3.0.0",
+    "@types/mdast": "^4.0.0",
+    "devlop": "^1.0.0",
+    "hast-util-to-jsx-runtime": "^2.0.0",
+    "html-url-attributes": "^3.0.0",
+    "mdast-util-to-hast": "^13.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.0.0",
+    "unified": "^11.0.0",
+    "unist-util-visit": "^5.0.0",
+    "vfile": "^6.0.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.35"
+  },
+  "devDependencies": {
+    "@testing-library/react": "16.3.2",
+    "@types/node": "^24.13.3",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@tsrx/react": "^0.2.56",
+    "concat-stream": "^2.0.0",
+    "global-jsdom": "^26.0.0",
+    "jsdom": "^26.0.0",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "react-markdown": "10.1.0",
+    "rehype-raw": "^7.0.0",
+    "rehype-starry-night": "^2.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-toc": "^9.0.0",
+    "vitest": "^4.1.10",
+    "@octanejs/testing-library": "0.1.32",
+    "octane": "0.1.35"
+  },
+  "scripts": {
+    "test": "pnpm upstream:verify && pnpm test:pristine && vitest run --config vitest.config.ts --root . tests/probes/async-component.server.test.ts tests/adoption/consumer.test.ts tests/adoption/consumer.server.test.ts tests/audit tests/differential tests/conformance tests/async tests/hooks tests/validation.test.ts",
+    "test:architecture": "vitest run --config vitest.config.ts --root . tests/probes/async-component.server.test.ts",
+    "test:pristine": "node ../../scripts/react-parity/node-full-runner.mjs --root packages/markdown/upstream/source --file packages/markdown/upstream/source/test.jsx --loader packages/markdown/upstream/source/script/load-jsx.js --inventory packages/markdown/audit/pristine-runtime.json",
+    "upstream:verify": "node audit/verify-provenance.mjs --self-test",
+    "typecheck": "tsrx-tsc --noEmit -p tsconfig.json && tsrx-tsc --noEmit -p typetests/tsconfig.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import type { ElementDescriptor } from 'octane';
+import { processSync } from './processor';
+import { projectTree } from './project';
+import type { Options } from './types';
+
+// OCTANE DIVERGENCE[react-markdown-react-image-preload][react-markdown:differential:image-preload]
+// React 19 server rendering may insert an image preload link; Octane renders the image element only.
+export function Markdown(options: Readonly<Options>): ElementDescriptor {
+	return projectTree(processSync(options), options.components);
+}
+
+export { Markdown as default };
+export { MarkdownAsync } from './markdown-async';
+export { MarkdownHooks } from './markdown-hooks.tsrx';
+export { defaultUrlTransform } from './url-transform';
+export type {
+	AllowElement,
+	Components,
+	ExtraProps,
+	HooksOptions,
+	Options,
+	UrlTransform,
+} from './types';

package/src/markdown-async.ts

@@ -0,0 +1,8 @@
+import type { ElementDescriptor } from 'octane';
+import { processAsync } from './processor';
+import { projectTree } from './project';
+import type { Options } from './types';
+
+export async function MarkdownAsync(options: Readonly<Options>): Promise<ElementDescriptor> {
+	return projectTree(await processAsync(options), options.components);
+}

package/src/markdown-hooks.tsrx

@@ -0,0 +1,36 @@
+import type { Root } from 'hast';
+import { useEffect, useState, type OctaneNode } from 'octane';
+import { createFile, createProcessor, transformTree } from './processor';
+import { projectTree } from './project';
+import type { HooksOptions } from './types';
+
+export function MarkdownHooks(options: Readonly<HooksOptions>): OctaneNode {
+	const processor = createProcessor(options);
+	const [error, setError] = useState<Error | undefined>(undefined);
+	const [tree, setTree] = useState<Root | undefined>(undefined);
+
+	useEffect(() => {
+		let cancelled = false;
+		const file = createFile(options);
+
+		processor.run(processor.parse(file), file, (nextError, nextTree) => {
+			if (!cancelled) {
+				setError(nextError);
+				setTree(nextTree);
+			}
+		});
+
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		options.children,
+		options.rehypePlugins,
+		options.remarkPlugins,
+		options.remarkRehypeOptions,
+	]);
+
+	if (error) throw error;
+
+	return tree ? projectTree(transformTree(tree, options), options.components) : options.fallback;
+}

package/src/processor.ts

@@ -0,0 +1,146 @@
+import { unreachable } from 'devlop';
+import type { Element, Nodes, Parents, Root } from 'hast';
+import { urlAttributes } from 'html-url-attributes';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import type { PluggableList } from 'unified';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+import { VFile } from 'vfile';
+import { isChildrenBlock } from 'octane';
+import type { Options } from './types';
+import { defaultUrlTransform } from './url-transform';
+
+const changelog = 'https://github.com/remarkjs/react-markdown/blob/main/changelog.md';
+const emptyPlugins: PluggableList = [];
+const emptyRemarkRehypeOptions = { allowDangerousHtml: true } as const;
+
+const deprecations = [
+	['astPlugins', 'remove-buggy-html-in-markdown-parser'],
+	['allowDangerousHtml', 'remove-buggy-html-in-markdown-parser'],
+	['allowNode', 'replace-allownode-allowedtypes-and-disallowedtypes', 'allowElement'],
+	['allowedTypes', 'replace-allownode-allowedtypes-and-disallowedtypes', 'allowedElements'],
+	['className', 'remove-classname'],
+	['disallowedTypes', 'replace-allownode-allowedtypes-and-disallowedtypes', 'disallowedElements'],
+	['escapeHtml', 'remove-buggy-html-in-markdown-parser'],
+	['includeElementIndex', '#remove-includeelementindex'],
+	['includeNodeIndex', 'change-includenodeindex-to-includeelementindex'],
+	['linkTarget', 'remove-linktarget'],
+	['plugins', 'change-plugins-to-remarkplugins', 'remarkPlugins'],
+	['rawSourcePos', '#remove-rawsourcepos'],
+	['renderers', 'change-renderers-to-components', 'components'],
+	['source', 'change-source-to-children', 'children'],
+	['sourcePos', '#remove-sourcepos'],
+	['transformImageUri', '#add-urltransform', 'urlTransform'],
+	['transformLinkUri', '#add-urltransform', 'urlTransform'],
+] as const;
+
+export function createProcessor(options: Readonly<Options>) {
+	const remarkRehypeOptions = options.remarkRehypeOptions
+		? { ...options.remarkRehypeOptions, ...emptyRemarkRehypeOptions }
+		: emptyRemarkRehypeOptions;
+
+	return unified()
+		.use(remarkParse)
+		.use(options.remarkPlugins || emptyPlugins)
+		.use(remarkRehype, remarkRehypeOptions)
+		.use(options.rehypePlugins || emptyPlugins);
+}
+
+export function createFile(options: Readonly<Options>): VFile {
+	const rawChildren = options.children;
+	if (isChildrenBlock(rawChildren)) {
+		unreachable(
+			'Unexpected compiled children block for `children` prop; use value-position JSX (`return <Markdown>…</Markdown>`) or pass an explicit `children` prop',
+		);
+	}
+	const children = rawChildren || '';
+	const file = new VFile();
+
+	if (typeof children === 'string') file.value = children;
+	else {
+		unreachable(
+			`Unexpected value \`${String(children)}\` for \`children\` prop, expected \`string\``,
+		);
+	}
+
+	return file;
+}
+
+export function processSync(options: Readonly<Options>): Root {
+	const processor = createProcessor(options);
+	const file = createFile(options);
+	return transformTree(processor.runSync(processor.parse(file), file), options);
+}
+
+export async function processAsync(options: Readonly<Options>): Promise<Root> {
+	const processor = createProcessor(options);
+	const file = createFile(options);
+	return transformTree(await processor.run(processor.parse(file), file), options);
+}
+
+export function transformTree<T extends Nodes>(tree: T, options: Readonly<Options>): T {
+	const allowedElements = options.allowedElements;
+	const allowElement = options.allowElement;
+	const disallowedElements = options.disallowedElements;
+	const skipHtml = options.skipHtml;
+	const unwrapDisallowed = options.unwrapDisallowed;
+	const urlTransform = options.urlTransform || defaultUrlTransform;
+	const optionRecord = options as Readonly<Record<string, unknown>>;
+
+	for (const [from, id, to] of deprecations) {
+		if (Object.hasOwn(optionRecord, from)) {
+			unreachable(
+				`Unexpected \`${from}\` prop, ${to ? `use \`${to}\` instead` : 'remove it'} (see <${changelog}#${id}> for more info)`,
+			);
+		}
+	}
+
+	if (allowedElements && disallowedElements) {
+		unreachable(
+			'Unexpected combined `allowedElements` and `disallowedElements`, expected one or the other',
+		);
+	}
+
+	visit(tree, (node, index, parent) => {
+		if (node.type === 'raw' && parent && typeof index === 'number') {
+			parent.children.splice(
+				index,
+				1,
+				...(skipHtml ? [] : [{ type: 'text', value: node.value } as const]),
+			);
+			return index;
+		}
+
+		if (node.type !== 'element') return;
+
+		for (const key in urlAttributes) {
+			if (Object.hasOwn(urlAttributes, key) && Object.hasOwn(node.properties, key)) {
+				const test = urlAttributes[key];
+				if (test === null || test.includes(node.tagName)) {
+					const value = node.properties[key];
+					node.properties[key] = urlTransform(String(value || ''), key, node);
+				}
+			}
+		}
+
+		let remove = allowedElements
+			? !allowedElements.includes(node.tagName)
+			: disallowedElements
+				? disallowedElements.includes(node.tagName)
+				: false;
+
+		if (!remove && allowElement && typeof index === 'number') {
+			remove = !allowElement(node, index, parent as Readonly<Parents> | undefined);
+		}
+
+		if (remove && parent && typeof index === 'number') {
+			parent.children.splice(index, 1, ...(unwrapDisallowed ? node.children : []));
+			return index;
+		}
+	});
+
+	return tree;
+}
+
+export type { Element, Options };

package/src/project.ts

@@ -0,0 +1,27 @@
+import type { Nodes } from 'hast';
+import { type Components as HastRuntimeComponents, toJsxRuntime } from 'hast-util-to-jsx-runtime';
+import { createElement, type ElementDescriptor, Fragment } from 'octane';
+import type { Components } from './types';
+
+type RuntimeElementType = Parameters<typeof createElement>[0];
+type RuntimeProps = Record<string, unknown> & { key?: string | number };
+
+function jsx(
+	type: RuntimeElementType,
+	props: RuntimeProps,
+	key?: string | number,
+): ElementDescriptor {
+	return createElement(type, key === undefined ? props : { ...props, key });
+}
+
+export function projectTree(tree: Nodes, components?: Components | null): ElementDescriptor {
+	return toJsxRuntime(tree, {
+		Fragment,
+		components: components as unknown as Partial<HastRuntimeComponents> | undefined,
+		ignoreInvalidStyle: true,
+		jsx,
+		jsxs: jsx,
+		passKeys: true,
+		passNode: true,
+	}) as ElementDescriptor;
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+import type { Element, Parents } from 'hast';
+import type { ComponentBody, OctaneNode } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+import type { Options as RemarkRehypeOptions } from 'remark-rehype';
+import type { PluggableList } from 'unified';
+
+export type AllowElement = (
+	element: Readonly<Element>,
+	index: number,
+	parent: Readonly<Parents> | undefined,
+) => boolean | null | undefined;
+
+export interface ExtraProps {
+	node?: Element | undefined;
+}
+
+export type Components = {
+	[Key in keyof Octane.JSX.IntrinsicElements]?:
+		| ComponentBody<Octane.JSX.IntrinsicElements[Key] & ExtraProps>
+		| keyof Octane.JSX.IntrinsicElements;
+};
+
+export type UrlTransform = (
+	url: string,
+	key: string,
+	node: Readonly<Element>,
+) => string | null | undefined;
+
+export interface Options {
+	allowElement?: AllowElement | null | undefined;
+	allowedElements?: ReadonlyArray<string> | null | undefined;
+	children?: string | null | undefined;
+	components?: Components | null | undefined;
+	disallowedElements?: ReadonlyArray<string> | null | undefined;
+	rehypePlugins?: PluggableList | null | undefined;
+	remarkPlugins?: PluggableList | null | undefined;
+	remarkRehypeOptions?: Readonly<RemarkRehypeOptions> | null | undefined;
+	skipHtml?: boolean | null | undefined;
+	unwrapDisallowed?: boolean | null | undefined;
+	urlTransform?: UrlTransform | null | undefined;
+}
+
+export interface HooksOptions extends Options {
+	fallback?: OctaneNode | null | undefined;
+}

package/src/url-transform.ts

@@ -0,0 +1,21 @@
+const safeProtocol = /^(https?|ircs?|mailto|xmpp)$/i;
+
+/** Preserve react-markdown's pinned default URL allowlist. */
+export function defaultUrlTransform(value: string): string {
+	const colon = value.indexOf(':');
+	const questionMark = value.indexOf('?');
+	const numberSign = value.indexOf('#');
+	const slash = value.indexOf('/');
+
+	if (
+		colon === -1 ||
+		(slash !== -1 && colon > slash) ||
+		(questionMark !== -1 && colon > questionMark) ||
+		(numberSign !== -1 && colon > numberSign) ||
+		safeProtocol.test(value.slice(0, colon))
+	) {
+		return value;
+	}
+
+	return '';
+}