@theseus.run/jsx-md 0.1.0

package/README.md

@@ -0,0 +1,323 @@
+# `@theseus.run/jsx-md`
+
+Built to manage agent instructions across multiple harnesses — [Copilot](https://github.com/features/copilot), [OpenCode](https://opencode.ai), and others. The content wasn't the problem. The management was.
+
+Agent instruction files grow. They develop conditional sections — capabilities that only apply to one harness, traits you're toggling between first-person and third-person to test what produces better behavior. A shared fragment between two agents becomes a copy-paste. A conditional becomes a ternary inside a template literal:
+
+```typescript
+const instructions = `
+You are a code reviewer.
+
+${harness === 'opencode' ? '<!-- use task() for subtasks -->' : ''}
+
+## Traits
+${firstPerson
+  ? '- I always verify output before claiming done.'
+  : '- The agent must verify output before claiming done.'}
+`
+```
+
+No syntax highlighting for the Markdown inside the string. No types on the structure. A variant is a new file. Refactoring is grep-and-pray.
+
+Nested lists make it worse. Markdown requires exact indentation — two spaces per level. Template strings force you to hardcode that spacing:
+
+```typescript
+const instructions = `
+## Rules
+
+- Outer rule
+  - Nested rule: two hardcoded spaces
+    - Deeper: four hardcoded spaces
+${condition ? '  - Conditional nested item' : ''}
+`
+```
+
+A false conditional leaves a blank bullet. The indentation is load-bearing and invisible. `DepthContext` in `@theseus.run/jsx-md` tracks nesting depth automatically — you write `<Ul>` inside `<Li>` and the renderer handles the spaces.
+
+This isn't an edge case. [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) — 39.8k stars, serious harness work — stores instructions the same way:
+
+```typescript
+export const PROMETHEUS_HIGH_ACCURACY_MODE = `# PHASE 3: PLAN GENERATION
+## High Accuracy Mode - MANDATORY LOOP
+\`\`\`typescript
+while (true) {
+  const result = task(subagent_type="momus", ...)
+  if (result.verdict === "OKAY") break
+}
+\`\`\`
+...` // 62 more lines of escaped template string
+```
+
+The escaped backticks are the tell — not a bad solution, it's the only solution the format offers. No composability, no reuse, no tooling support.
+
+The web dev world solved "structured text with conditionals and composable fragments" ten years ago. JSX is a transform spec, not a React dependency — `jsxImportSource` lets you point it at any runtime. `@theseus.run/jsx-md` is a runtime that outputs Markdown:
+
+```tsx
+const ReviewerInstructions = ({ harness, firstPerson }: Props) => (
+  <>
+    <P>You are a code reviewer.</P>
+    {harness === 'opencode' && (
+      <HtmlComment>use task() for subtasks</HtmlComment>
+    )}
+    <H2>Traits</H2>
+    <Ul>
+      <Li>
+        {firstPerson
+          ? 'I always verify output before claiming done.'
+          : 'The agent must verify output before claiming done.'}
+      </Li>
+    </Ul>
+  </>
+)
+
+render(<ReviewerInstructions harness="opencode" firstPerson={true} />)
+```
+
+No escaped backticks. Syntax highlighting in your editor. Conditionals are JSX expressions. Variants are props. Shared fragments are components.
+
+`render()` returns a plain string — no virtual DOM, no hydration, no React runtime anywhere in the chain.
+
+---
+
+## Install
+
+```bash
+bun add @theseus.run/jsx-md
+```
+
+Then in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@theseus.run/jsx-md"
+  }
+}
+```
+
+---
+
+## What you're getting
+
+**Zero runtime dependencies.** The package ships TypeScript source with no third-party imports. Nothing gets added to your bundle.
+
+**Bun-first.** Ships TypeScript source directly, no compiled output. Works transparently in Bun: install, add two tsconfig lines, write TSX. The trade-off is real: vanilla Node.js without a bundler won't run `.ts` files from `node_modules`. If your stack is Vite, tsup, or esbuild, those handle it. If you're running bare Node, v0.1.0 doesn't have a solution for you yet.
+
+**JSX without React.** When you write `<H2>Title</H2>`, the transform calls `jsx(H2, { children: "Title" })`. `H2` is a plain function — takes props, returns a string. No virtual DOM, no reconciler, no fiber, no hooks. `render()` walks the VNode tree synchronously and concatenates. The output is deterministic: same input, same string, every time. You can test it with `expect(render(<MyPrompt />)).toMatchSnapshot()`.
+
+**TypeScript-first.** All components and their props are typed. `render()` accepts `VNode`, returns `string`. Wrong usage is a compile error, not a runtime surprise.
+
+**String children are verbatim.** `render()` passes raw string values through without escaping. `<P>{"<b>text</b>"}</P>` outputs `<b>text</b>` — no transformation. For LLM prompts this is the right default; Markdown renderers handle the rest.
+
+**XML-structured prompts, zero config.** Any lowercase JSX tag renders as an XML block — `<context>`, `<instructions>`, `<example index={1}>`. Anthropic's prompt engineering guide recommends this structure for Claude agents. Attributes are typed and serialized automatically; empty tags self-close. No imports, no registration — it's built into the JSX intrinsics catch-all.
+
+---
+
+## Usage
+
+```tsx
+// system-prompt.tsx
+import { render, H2, P, Ul, Li, Bold, Code } from "@theseus.run/jsx-md";
+
+const prompt = render(
+  <>
+    <H2>Role</H2>
+    <P>
+      You are a precise code reviewer. Your job is to find bugs, not suggest
+      style changes.
+    </P>
+
+    <H2>Rules</H2>
+    <Ul>
+      <Li>
+        Flag <Bold>P0</Bold> issues immediately — do not bury them.
+      </Li>
+      <Li>
+        Use <Code>inline code</Code> when referencing identifiers.
+      </Li>
+      <Li>One finding per comment. No compound observations.</Li>
+    </Ul>
+
+    <H2>Output format</H2>
+    <P>
+      Respond with a structured list. Each item: severity, location, finding.
+    </P>
+  </>
+);
+
+console.log(prompt);
+```
+
+Output:
+
+```markdown
+## Role
+
+You are a precise code reviewer. Your job is to find bugs, not suggest style changes.
+
+## Rules
+
+- Flag **P0** issues immediately — do not bury them.
+- Use `inline code` when referencing identifiers.
+- One finding per comment. No compound observations.
+
+## Output format
+
+Respond with a structured list. Each item: severity, location, finding.
+```
+
+---
+
+## Structured agent instructions
+
+Anthropic's prompt engineering guide recommends XML tags to structure Claude prompts — wrapping each content type in its own tag reduces misinterpretation. `<instructions>`, `<context>`, `<examples>`, `<document index="n">` are the documented patterns.
+
+Any lowercase JSX tag is an XML intrinsic in `@theseus.run/jsx-md`. No imports, no registration:
+
+```tsx
+const ReviewerPrompt = ({ repo, examples }: Props) => (
+  <>
+    <context>
+      <P>Repository: {repo}. Language: TypeScript. Package manager: bun.</P>
+    </context>
+
+    <instructions>
+      <H2>Role</H2>
+      <P>You are a precise code reviewer. Find bugs, not style issues.</P>
+
+      <H2>Rules</H2>
+      <Ul>
+        <Li>Flag <Bold>P0</Bold> issues first — do not bury them.</Li>
+        <Li>One finding per comment. No compound observations.</Li>
+        <Li>Use <Code>inline code</Code> when referencing identifiers.</Li>
+      </Ul>
+    </instructions>
+
+    {examples.length > 0 && (
+      <examples>
+        {examples.map((ex, i) => (
+          <example index={i + 1}>
+            <Md>{ex}</Md>
+          </example>
+        ))}
+      </examples>
+    )}
+  </>
+)
+```
+
+Output:
+
+```
+<context>
+Repository: cockpit. Language: TypeScript. Package manager: bun.
+</context>
+
+<instructions>
+## Role
+
+You are a precise code reviewer. Find bugs, not style issues.
+
+## Rules
+
+- Flag **P0** issues first — do not bury them.
+- One finding per comment. No compound observations.
+- Use `inline code` when referencing identifiers.
+</instructions>
+
+<examples>
+  <example index="1">
+    ... your example content ...
+  </example>
+</examples>
+```
+
+Attributes are typed (`index={1}` → `index="1"`), boolean `true` attrs render bare, `false`/`null`/`undefined` are omitted. Empty tags self-close: `<tag />`.
+
+---
+
+## Primitives
+
+| Component | Markdown output |
+|-----------|----------------|
+| `H1`–`H6` | `#`–`######` headings |
+| `P` | Paragraph (blank line separated) |
+| `Hr` | `---` horizontal rule |
+| `Codeblock` | Fenced code block with optional `lang` prop |
+| `Blockquote` | `>` blockquote |
+| `Ul` | Unordered list |
+| `Ol` | Ordered list |
+| `Li` | List item (supports nesting via `Ul`/`Ol` inside `Li`) |
+| `TaskList` | Task list container |
+| `Task` | `- [ ]` / `- [x]` task item (`done` prop) |
+| `Table` | Markdown table |
+| `Tr` | Table row |
+| `Th` | Table header cell |
+| `Td` | Table data cell |
+| `Bold` | `**bold**` |
+| `Code` | `` `inline code` `` |
+| `Italic` | `*italic*` |
+| `Strikethrough` | `~~strikethrough~~` |
+| `Link` | `[text](url)` |
+| `Img` | `![alt](src)` |
+| `Md` | Raw markdown passthrough (escape hatch for complex inline combinations) |
+| `HtmlComment` | `<!-- comment -->` (invisible to most renderers; useful for LLM-only instructions) |
+| `Details` | `<details><summary>` collapsible block |
+| `Callout` | GitHub-style admonition with `type` prop: `note`, `tip`, `important`, `warning`, `caution` |
+
+---
+
+## Roadmap
+
+**v0.1.0** — current. TypeScript source, Bun-first. Markdown primitives + XML intrinsic elements.
+
+**v0.2.0** — two additions:
+
+- _Context API (public)._ `DepthContext` already uses an internal context system for list nesting. v0.2.0 exposes this as a first-class public API. The pattern is React-familiar but synchronous and string-based.
+
+  Should fix prop-drilling. A prompt tree with conditional sections per harness ends up threading `harness` through every component:
+
+  ```tsx
+  // v0.1.0 — prop-drilling
+  const Prompt = ({ harness }: Props) => (
+    <>
+      <Instructions harness={harness} />
+      <Rules harness={harness} />
+      <Examples harness={harness} />
+    </>
+  )
+  ```
+
+  With the v0.2.0 context API, set it once at the root and read it anywhere:
+
+  ```tsx
+  // v0.2.0 — context
+  const HarnessContext = createContext<'opencode' | 'copilot'>('copilot')
+
+  const prompt = render(
+    <HarnessContext.Provider value="opencode">
+      <Prompt />
+    </HarnessContext.Provider>
+  )
+
+  // In any component, at any depth — no prop threading:
+  const Instructions = () => {
+    const harness = useContext(HarnessContext)
+    return harness === 'opencode'
+      ? <P>Use task() for subtasks.</P>
+      : null
+  }
+  ```
+
+- _Node.js compiled output._ Ships a compiled `dist/` alongside the TypeScript source. Unblocks bare Node.js without a bundler.
+
+---
+
+## License
+
+MIT — see [LICENSE](../../LICENSE). 
+
+Built by [Roman Dubinin](https://romanonthego.com). 
+
+Part of [Theseus](https://theseus.run).

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@theseus.run/jsx-md",
+  "version": "0.1.0",
+  "description": "JSX/TSX renderer for Markdown. Write agent prompts and LLM instructions as typed, composable components. Zero runtime dependencies.",
+  "type": "module",
+  "author": "Roman Dubinin <romanonthego@gmail.com> (https://romanonthego.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theseus-run/theseus.git",
+    "directory": "packages/jsx-md"
+  },
+  "bugs": {
+    "url": "https://github.com/theseus-run/theseus/issues"
+  },
+  "homepage": "https://theseus.run",
+  "keywords": ["jsx", "tsx", "markdown", "llm", "agents", "prompts", "jsx-runtime"],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "files": [
+    "src/index.ts",
+    "src/render.ts",
+    "src/primitives.tsx",
+    "src/jsx-runtime.ts",
+    "src/jsx-dev-runtime.ts",
+    "src/context.ts",
+    "src/escape.ts",
+    "src/_render-registry.ts"
+  ],
+  "sideEffects": false,
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/_render-registry.ts

@@ -0,0 +1,16 @@
+type RenderFn = (node: unknown) => string;
+
+let _render: RenderFn | null = null;
+
+export function registerRender(fn: RenderFn): void {
+  _render = fn;
+}
+
+export function callRender(node: unknown): string {
+  if (!_render) {
+    throw new Error(
+      "jsx-md: render not initialized. Ensure 'render' is imported from '@theseus.run/jsx-md' before Fragment is called.",
+    );
+  }
+  return _render(node);
+}

package/src/context.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal synchronous context API for jsx-md.
+ *
+ * Uses a module-level stack map so context values are available synchronously
+ * during the render() traversal. Not safe for async or concurrent rendering.
+ */
+
+export interface Context<T> {
+  readonly _id: symbol;
+  readonly _default: T;
+}
+
+/**
+ * Process-wide singleton. Not safe for concurrent render() calls in the same
+ * process (e.g. simultaneous Bun HTTP requests). For agent prompt generation
+ * this is almost always a non-issue — renders are sequential.
+ */
+const stack = new Map<symbol, unknown[]>();
+
+export function createContext<T>(defaultValue: T): Context<T> {
+  return { _id: Symbol(), _default: defaultValue };
+}
+
+export function useContext<T>(ctx: Context<T>): T {
+  const s = stack.get(ctx._id);
+  if (!s || s.length === 0) {
+    return ctx._default;
+  }
+  return s[s.length - 1] as T;
+}
+
+export function withContext<T>(ctx: Context<T>, value: T, fn: () => string): string {
+  let s = stack.get(ctx._id);
+  if (!s) {
+    s = [];
+    stack.set(ctx._id, s);
+  }
+  s.push(value);
+  try {
+    return fn();
+  } finally {
+    s.pop();
+  }
+}

package/src/escape.ts

@@ -0,0 +1,36 @@
+/**
+ * Escapes `&`, `"`, `<`, `>` — for use in XML/HTML attribute values.
+ * Escapes for double-quoted HTML/XML attribute values. Single quotes are not
+ * escaped — do not use this in single-quoted attribute contexts.
+ */
+export function escapeHtmlAttr(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/** Escapes `&`, `<`, `>` — for use in HTML/XML text content (not attributes). */
+export function escapeHtmlContent(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Percent-encodes `(` and `)` in a URL to prevent premature link termination in
+ * Markdown link syntax `[text](url)`.
+ */
+export function encodeLinkUrl(url: string): string {
+  return url.replace(/[()]/g, (c) => encodeURIComponent(c));
+}
+
+/**
+ * Percent-encodes `[` and `]` in text used as Markdown link label (image alt).
+ * Prevents premature bracket closure in `![alt](src)`.
+ */
+export function encodeLinkLabel(text: string): string {
+  return text.replace(/[[\]]/g, (c) => encodeURIComponent(c));
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Runtime exports
+export { jsx, jsxs, Fragment } from './jsx-runtime.ts';
+export type { JSX, VNode, VNodeElement } from './jsx-runtime.ts';
+
+// Render
+export { render } from './render.ts';
+
+// Context API
+export { createContext, useContext, withContext } from './context.ts';
+export type { Context } from './context.ts';
+
+// Primitive components
+export {
+  H1, H2, H3, H4, H5, H6,
+  P,
+  Hr,
+  Codeblock,
+  Blockquote,
+  Li, Ul, Ol,
+  Bold, Code, Italic, Strikethrough, Link, Img,
+  Md,
+  Table, Tr, Th, Td,
+  TaskList, Task,
+  Callout,
+  HtmlComment,
+  Details,
+} from './primitives.tsx';
+
+export type { CalloutType } from './primitives.tsx';

package/src/jsx-dev-runtime.ts

@@ -0,0 +1,4 @@
+// Dev mode — re-export everything from jsx-runtime, aliasing jsx as jsxDEV.
+// Bun resolves ./jsx-dev-runtime in development builds and calls jsxDEV.
+export { jsx as jsxDEV, jsxs, Fragment } from './jsx-runtime.ts';
+export type { VNode, VNodeElement } from './jsx-runtime.ts';

package/src/jsx-runtime.ts

@@ -0,0 +1,94 @@
+/**
+ * Custom JSX-to-VNode runtime for agent markdown generation.
+ *
+ * Bun's JSX compilation with `jsxImportSource: "@theseus.run/jsx-md"` resolves
+ * `jsx` and `jsxs` from `@theseus.run/jsx-md/jsx-runtime`. The factory builds
+ * a VNode tree — no evaluation at construction time.
+ *
+ * Call `render(node)` from `./render.ts` to produce the final markdown string.
+ * All markdown primitives live in primitives.tsx as named components.
+ *
+ * Fragment circular-dep resolution: Fragment needs render() to flatten children,
+ * but render.ts imports types from this file. We use _render-registry.ts as a
+ * shared side-channel: render.ts calls registerRender(render) on module init,
+ * Fragment defers to callRender(). Any entry point that imports render will
+ * register it before rendering starts.
+ */
+
+import { callRender } from './_render-registry.ts';
+
+// ---------------------------------------------------------------------------
+// VNode types
+// ---------------------------------------------------------------------------
+
+export type VNodeElement = {
+  readonly type: Component | string;
+  readonly props: Record<string, unknown>;
+};
+
+export type VNode =
+  | null
+  | undefined
+  | boolean
+  | string
+  | number
+  | VNodeElement
+  | ReadonlyArray<VNode>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Component<P = any> = (props: P) => string;
+
+// ---------------------------------------------------------------------------
+// JSX namespace
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace JSX {
+  /**
+   * JSX.Element is VNode (not just VNodeElement) so that string-returning
+   * components pass TypeScript's component return-type check. The jsx() factory
+   * always produces VNodeElement at runtime; the wider union here is only needed
+   * to satisfy TypeScript's component-validity check.
+   */
+  export type Element = VNode;
+
+  // Catch-all — allows arbitrary lowercase XML tags as intrinsic elements.
+  export interface IntrinsicElements {
+    [tag: string]: { children?: VNode; [attr: string]: unknown };
+  }
+
+  export interface ElementChildrenAttribute {
+    children: VNode;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Render registration (avoids circular dep with render.ts)
+// ---------------------------------------------------------------------------
+
+// Registration and dispatch are handled by _render-registry.ts.
+// render.ts calls registerRender(render) on module init.
+// Fragment calls callRender() to evaluate children.
+
+// ---------------------------------------------------------------------------
+// JSX factory
+// ---------------------------------------------------------------------------
+
+/**
+ * JSX factory — called by Bun's compiled JSX. Builds VNode tree; no evaluation.
+ *
+ * `type` is a function component or a string tag name. String tags are rendered
+ * as XML blocks by render.ts: `<tag attrs>\ncontent\n</tag>\n` (or self-closing
+ * when the inner content is empty).
+ */
+export function jsx(type: Component | string, props: Record<string, unknown>): VNodeElement {
+  return { type, props };
+}
+
+/** jsxs — same as jsx, used when there are multiple children (children is array) */
+export const jsxs = jsx;
+
+/** Fragment — renders children. Defers to _render-registry to avoid circular imports. */
+export function Fragment({ children }: { children?: VNode }): string {
+  return callRender(children ?? null);
+}

package/src/primitives.tsx

@@ -0,0 +1,383 @@
+/**
+ * Markdown primitives as named TSX components.
+ *
+ * Components covering all markdown formatting needs:
+ *   Block:  H1, H2, H3, H4, H5, H6, P, Hr, Codeblock, Blockquote
+ *   List:   Ol, Ul, Li, TaskList, Task
+ *   Table:  Table, Tr, Th, Td
+ *   Inline: Bold, Code, Italic, Strikethrough, Link, Img
+ *   Raw:    Md
+ *   Other:  Callout, HtmlComment, Details
+ *
+ * Each is a plain function (props) => string. No React. No DOM.
+ *
+ * Children are passed as VNode (unevaluated). Each component calls
+ * render(children) to produce the final string. This enables context
+ * propagation — Ul/Ol wrap render in a withContext(DepthContext, depth+1)
+ * call so nested Li components can compute their indentation level.
+ *
+ * ---------------------------------------------------------------------------
+ * AUTHORING RULES
+ * ---------------------------------------------------------------------------
+ *
+ * 1. Prefer components over inline markdown strings.
+ *
+ *      **text**        →  <Bold>text</Bold>
+ *      `text`          →  <Code>text</Code>
+ *      *text*          →  <Italic>text</Italic>
+ *      [label](url)    →  <Link href="url">label</Link>
+ *
+ * 2. Bare JSX text for plain prose. {'...'} only when the string contains
+ *    a character JSX cannot represent as bare text:
+ *
+ *      Requires {'...'}:  backtick  {  }  <  >  '
+ *      Bare text is fine: letters, spaces, digits, . , : ; ! ? — – - ( ) [ ] " & * + = | / \
+ *
+ *      // WRONG — unnecessary wrapper
+ *      <Li><Bold>P1</Bold>{': Guard clauses over nesting.'}</Li>
+ *
+ *      // CORRECT — bare text
+ *      <Li><Bold>P1</Bold>: Guard clauses over nesting.</Li>
+ *
+ *      // CORRECT — must wrap, contains single quote
+ *      <Li><Bold>P1</Bold>{": Dead code: delete, don't comment out."}</Li>
+ *
+ *      // CORRECT — must wrap, contains backtick
+ *      <P>{'Format: `ROI≈X.X`'}</P>
+ *
+ * 3. Md is an escape hatch for genuinely undecomposable strings — typically
+ *    4+ inline code spans mixed with bold and prose. Use sparingly.
+ *
+ *      // Legitimate Md use — 6 code spans, decomposition adds noise
+ *      <Li><Md>{'**P0**: Type = `TKey`. Not `TFuncKey`, `string`, or `<Trans>`.'}</Md></Li>
+ *
+ *      // Not legitimate — decompose instead
+ *      <Li><Md>{'**P1**: Guard clauses over nesting.'}</Md></Li>
+ *
+ * 4. Nested lists are supported via nested Ul inside Li children.
+ *    DepthContext tracks the nesting level and computes indentation automatically.
+ *
+ *      <Ul>
+ *        <Li>top-level item
+ *          <Ul><Li>sub-item one</Li><Li>sub-item two</Li></Ul>
+ *        </Li>
+ *      </Ul>
+ *
+ * 5. Ol must be at document root (depth 0). Nesting Ol anywhere inside a Ul —
+ *    including inside a Li — throws at runtime because depth > 0.
+ *    Ol is for flat, top-level numbered sequences only.
+ */
+
+/* @jsxImportSource @theseus.run/jsx-md */
+
+import type { VNode } from './jsx-runtime.ts';
+import { render } from './render.ts';
+import { createContext, useContext, withContext } from './context.ts';
+import { escapeHtmlContent, encodeLinkUrl, encodeLinkLabel } from './escape.ts';
+
+// ---------------------------------------------------------------------------
+// DepthContext — tracks list nesting level for Li indentation
+// ---------------------------------------------------------------------------
+
+/** Tracks the current list nesting depth. 0 = outside any list. */
+const DepthContext = createContext(0);
+
+// ---------------------------------------------------------------------------
+// OlContext — signals that Li is inside an Ol (uses sentinel marker)
+// ---------------------------------------------------------------------------
+
+/**
+ * Signals that the current Li is being rendered inside an Ol.
+ * Li emits a sentinel prefix (\x01) instead of "- " when this is true,
+ * preventing Ol's post-processor from matching literal "- " content.
+ */
+const OlContext = createContext(false);
+
+// ---------------------------------------------------------------------------
+// Block elements — trailing \n\n
+// ---------------------------------------------------------------------------
+
+interface BlockProps {
+  children?: VNode;
+}
+
+export function H1({ children }: BlockProps): string {
+  return `# ${render(children ?? null)}\n\n`;
+}
+
+export function H2({ children }: BlockProps): string {
+  return `## ${render(children ?? null)}\n\n`;
+}
+
+export function H3({ children }: BlockProps): string {
+  return `### ${render(children ?? null)}\n\n`;
+}
+
+export function H4({ children }: BlockProps): string {
+  return `#### ${render(children ?? null)}\n\n`;
+}
+
+export function H5({ children }: BlockProps): string {
+  return `##### ${render(children ?? null)}\n\n`;
+}
+
+export function H6({ children }: BlockProps): string {
+  return `###### ${render(children ?? null)}\n\n`;
+}
+
+export function P({ children }: BlockProps): string {
+  return `${render(children ?? null)}\n\n`;
+}
+
+export function Hr(): string {
+  return '---\n\n';
+}
+
+interface CodeblockProps {
+  lang?: string;
+  children?: VNode;
+  indent?: number;
+}
+
+export function Codeblock({ lang = '', children, indent = 0 }: CodeblockProps): string {
+  const prefix = ' '.repeat(indent);
+  const rawLines = render(children ?? null).split('\n');
+  // Drop trailing empty entries produced by a trailing \n in content to prevent
+  // a spurious indented blank line appearing before the closing fence.
+  while (rawLines.length > 0 && rawLines[rawLines.length - 1] === '') {
+    rawLines.pop();
+  }
+  const body = rawLines.map((line) => prefix + line).join('\n');
+  return `\`\`\`${lang}\n${body}\n\`\`\`\n\n`;
+}
+
+/**
+ * Blockquote — prefixes every content line with `> `.
+ * Trailing blank lines are stripped before prefixing so the output ends
+ * cleanly with `\n\n` rather than `> \n> \n\n`.
+ * Empty lines within the content get a bare `>` (no trailing space) to
+ * avoid invisible trailing whitespace in the rendered output.
+ * Nested blockquotes compose naturally: the inner renders `> text\n\n`,
+ * trimEnd strips the trailing newlines, then the outer prefixes each line
+ * with `> `, producing `> > text`.
+ */
+export function Blockquote({ children }: BlockProps): string {
+  const content = render(children ?? null).trimEnd();
+  const lines = content.split('\n').map((line) => (line === '' ? '>' : `> ${line}`)).join('\n');
+  return `${lines}\n\n`;
+}
+
+// ---------------------------------------------------------------------------
+// List elements
+// ---------------------------------------------------------------------------
+
+export function Ul({ children }: BlockProps): string {
+  const depth = useContext(DepthContext);
+  // Reset OlContext so Li items inside a Ul nested within Ol emit "- " not the Ol sentinel
+  const rendered = withContext(OlContext, false, () =>
+    withContext(DepthContext, depth + 1, () => render(children ?? null)),
+  );
+  // Add trailing newline only at the outermost list level
+  return depth === 0 ? `${rendered}\n` : rendered;
+}
+
+/**
+ * Ordered list — auto-numbers Li children at the current depth level.
+ *
+ * Ul/Ol increment the depth before rendering children, so Li items know
+ * their indentation. When OlContext is true, Li emits a sentinel prefix
+ * (\x01) instead of "- ", which Ol replaces with numbered prefixes. This
+ * prevents false matches on Li content that literally begins with "- ".
+ *
+ * Constraint: Ol must be at document root (depth 0). Nesting Ol anywhere
+ * inside a Ul — including inside a Li — throws at runtime because depth > 0.
+ * Ol is for flat, top-level numbered sequences only.
+ */
+export function Ol({ children }: BlockProps): string {
+  const depth = useContext(DepthContext);
+  if (depth > 0) {
+    throw new Error('Ol cannot be used inside any list container (Ul, Ol, or TaskList) — depth must be 0.');
+  }
+  const MARKER = '\x01';
+  const rendered = withContext(OlContext, true, () =>
+    withContext(DepthContext, depth + 1, () => render(children ?? null)),
+  );
+  let counter = 0;
+  return rendered.replace(/^\x01/gm, () => `${++counter}. `) + '\n';
+}
+
+export function Li({ children }: BlockProps): string {
+  const depth = useContext(DepthContext);
+  const isInOl = useContext(OlContext);
+  // depth is already incremented by the enclosing Ul/Ol, so depth 1 = top-level.
+  // Math.max guard: safe when Li is used outside Ul/Ol (depth=0).
+  const indent = '  '.repeat(Math.max(0, depth - 1));
+  const inner = render(children ?? null).trimEnd();
+  if (isInOl) {
+    // \x01 is the sentinel Ol replaces with a number — prevents "- " content from being matched
+    return `${indent}\x01${inner}\n`;
+  }
+  return `${indent}- ${inner}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Table elements
+// ---------------------------------------------------------------------------
+
+/**
+ * Th and Td are semantically identical in GFM — position determines header
+ * styling, not cell type. Both return ` content |` (trailing pipe delimiter).
+ * Tr prepends the leading `|` to form a complete row line.
+ */
+export function Th({ children }: { children?: VNode }): string {
+  return ` ${render(children ?? null)} |`;
+}
+
+export function Td({ children }: { children?: VNode }): string {
+  return ` ${render(children ?? null)} |`;
+}
+
+export function Tr({ children }: { children?: VNode }): string {
+  return `|${render(children ?? null)}\n`;
+}
+
+/**
+ * Table — renders Tr children, then injects a GFM separator row after the
+ * first row (the header). Column count is derived from the first row's pipe
+ * count so no column metadata needs to be threaded through context.
+ */
+export function Table({ children }: { children?: VNode }): string {
+  const rendered = render(children ?? null);
+  const lines = rendered.split('\n').filter((l) => l.trim().length > 0);
+  if (lines.length === 0) {
+    return '';
+  }
+  const headerLine = lines[0]!;
+  const colCount = headerLine.split('|').filter((s) => s.trim().length > 0).length;
+  const separator = '| ' + Array(colCount).fill('---').join(' | ') + ' |';
+  const bodyLines = lines.slice(1);
+  return [headerLine, separator, ...bodyLines].join('\n') + '\n\n';
+}
+
+// ---------------------------------------------------------------------------
+// Inline elements — no trailing whitespace
+// ---------------------------------------------------------------------------
+
+interface InlineProps {
+  children?: VNode;
+}
+
+export function Bold({ children }: InlineProps): string {
+  return `**${render(children ?? null)}**`;
+}
+
+export function Code({ children }: InlineProps): string {
+  return `\`${render(children ?? null)}\``;
+}
+
+export function Italic({ children }: InlineProps): string {
+  return `*${render(children ?? null)}*`;
+}
+
+export function Strikethrough({ children }: InlineProps): string {
+  return `~~${render(children ?? null)}~~`;
+}
+
+interface LinkProps {
+  href: string;
+  children?: VNode;
+}
+
+export function Link({ href, children }: LinkProps): string {
+  return `[${render(children ?? null)}](${encodeLinkUrl(href)})`;
+}
+
+interface ImgProps {
+  src: string;
+  alt?: string;
+}
+
+export function Img({ src, alt = '' }: ImgProps): string {
+  return `![${encodeLinkLabel(alt)}](${encodeLinkUrl(src)})`;
+}
+
+// ---------------------------------------------------------------------------
+// Raw passthrough — escape hatch only, see AUTHORING RULES above
+// ---------------------------------------------------------------------------
+
+export function Md({ children }: BlockProps): string {
+  return render(children ?? null);
+}
+
+// ---------------------------------------------------------------------------
+// TaskList + Task — GFM task list items
+// ---------------------------------------------------------------------------
+
+export function TaskList({ children }: { children?: VNode }): string {
+  const depth = useContext(DepthContext);
+  const rendered = withContext(DepthContext, depth + 1, () => render(children ?? null));
+  // Mirror Ul: trailing \n only at outermost task list level
+  return depth === 0 ? `${rendered}\n` : rendered;
+}
+
+export function Task({ children, done }: { children?: VNode; done?: boolean }): string {
+  const depth = useContext(DepthContext);
+  // Math.max guard matches Li's defensive pattern — safe when Task is used outside TaskList (depth=0)
+  const indent = '  '.repeat(Math.max(0, depth - 1));
+  const prefix = done ? '[x]' : '[ ]';
+  // NOTE: nested TaskList inside a Task appends first inner item inline (same known
+  // limitation as Li with nested Ul — structural fix requires block-aware rendering)
+  const inner = render(children ?? null).trimEnd();
+  return `${indent}- ${prefix} ${inner}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Callout — GitHub-flavored alert blockquote
+// ---------------------------------------------------------------------------
+
+export type CalloutType = 'note' | 'tip' | 'important' | 'warning' | 'caution';
+
+export function Callout({
+  children,
+  type,
+}: {
+  children?: VNode;
+  type: CalloutType;
+}): string {
+  const inner = render(children ?? null).trimEnd();
+  const lines = inner.split('\n').map((line) => (line === '' ? '>' : `> ${line}`)).join('\n');
+  return `> [!${type.toUpperCase()}]\n${lines}\n\n`;
+}
+
+// ---------------------------------------------------------------------------
+// HtmlComment — renders <!-- content --> (single-line or multi-line)
+// ---------------------------------------------------------------------------
+
+export function HtmlComment({ children }: { children?: VNode }): string {
+  const inner = render(children ?? null).trimEnd();
+  // Use .trim() only for the empty-check: whitespace-only content → <!-- -->
+  if (!inner.trim()) {
+    return `<!-- -->\n`;
+  }
+  if (inner.includes('\n')) {
+    return `<!--\n${inner}\n-->\n`;
+  }
+  return `<!-- ${inner} -->\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Details — GitHub collapsible section
+// ---------------------------------------------------------------------------
+
+export function Details({
+  children,
+  summary,
+}: {
+  children?: VNode;
+  summary: string;
+}): string {
+  // trimEnd() required: GitHub needs a blank line before </details> to render body as markdown.
+  // The \n\n in the template provides that; trimEnd prevents double-blank-lines.
+  const body = render(children ?? null).trimEnd();
+  return `<details>\n<summary>${escapeHtmlContent(summary)}</summary>\n\n${body}\n\n</details>\n`;
+}

package/src/render.ts

@@ -0,0 +1,60 @@
+/**
+ * render() — converts a VNode tree to a markdown string.
+ *
+ * This is the top-down evaluation pass. Components in the tree are called
+ * here, not at JSX construction time. Children are passed as raw VNode values
+ * to each component so they can wrap rendering in context (e.g. DepthContext).
+ *
+ * Registers itself with the render registry (via _render-registry.ts) on module
+ * init to provide Fragment with a render reference without a circular import.
+ */
+
+import { registerRender } from './_render-registry.ts';
+import { escapeHtmlAttr } from './escape.ts';
+import { type VNode, type VNodeElement } from './jsx-runtime.ts';
+
+function isVNodeElement(node: VNode): node is VNodeElement {
+  return typeof node === 'object' && node !== null && !Array.isArray(node);
+}
+
+export function render(node: VNode): string {
+  if (node === null || node === undefined || node === false || node === true) {
+    return '';
+  }
+  if (typeof node === 'string') {
+    return node;
+  }
+  if (typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return (node as ReadonlyArray<VNode>).map(render).join('');
+  }
+  // VNodeElement — dispatch on type
+  if (!isVNodeElement(node)) {
+    return '';
+  }
+  const el = node; // narrowed to VNodeElement
+
+  // String type → render as an XML block tag
+  if (typeof el.type === 'string') {
+    const { children, ...attrs } = el.props;
+    const attrStr = Object.entries(attrs)
+      .filter(([, v]) => v !== undefined && v !== null && v !== false)
+      .map(([k, v]) => (v === true ? ` ${k}` : ` ${k}="${escapeHtmlAttr(String(v))}"`))
+      .join('');
+    const inner = render(children as VNode ?? null);
+    if (inner === '') {
+      return `<${el.type}${attrStr} />\n`;
+    }
+    return `<${el.type}${attrStr}>\n${inner.trimEnd()}\n</${el.type}>\n`;
+  }
+
+  // Function component — call with its props (children still as VNode)
+  return el.type(el.props);
+}
+
+// Register render with Fragment immediately on module init.
+// Any entry point that imports render will trigger this before rendering starts.
+// Cast is safe: callRender passes only VNode values to render at runtime.
+registerRender(render as (node: unknown) => string);