@theseus.run/jsx-md 0.1.1 → 0.2.0

package/src/primitives.tsx

@@ -54,7 +54,7 @@
  *      // Not legitimate — decompose instead
  *      <Li><Md>{'**P1**: Guard clauses over nesting.'}</Md></Li>
  *
- * 4. Nested lists are supported via nested Ul inside Li children.
+ * 4. Nested lists are fully supported via nested Ul or Ol inside Li children.
  *    DepthContext tracks the nesting level and computes indentation automatically.
  *
  *      <Ul>
@@ -63,9 +63,11 @@
  *        </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.
+ *      <Ol>
+ *        <Li>step one
+ *          <Ol><Li>sub-step a</Li><Li>sub-step b</Li></Ol>
+ *        </Li>
+ *      </Ol>
  */
 
 /* @jsxImportSource @theseus.run/jsx-md */
@@ -73,7 +75,7 @@
 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';
+import { escapeHtmlContent, encodeLinkUrl, encodeLinkLabel, backtickFenceLength, escapeMarkdown } from './escape.ts';
 
 // ---------------------------------------------------------------------------
 // DepthContext — tracks list nesting level for Li indentation
@@ -83,15 +85,43 @@ import { escapeHtmlContent, encodeLinkUrl, encodeLinkLabel } from './escape.ts';
 const DepthContext = createContext(0);
 
 // ---------------------------------------------------------------------------
-// OlContext — signals that Li is inside an Ol (uses sentinel marker)
+// OlCollectorContext — collects Li items for Ol numbering
 // ---------------------------------------------------------------------------
 
 /**
- * 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.
+ * Mutable item-collector box passed through context during Ol rendering.
+ * Li pushes its rendered content into collector.items (and returns '') when
+ * an OlCollector is present; Ol reads the items after rendering to number them.
+ * This eliminates the sentinel-character post-processing hack and allows Ol
+ * to be nested at any depth, just like Ul.
  */
-const OlContext = createContext(false);
+type OlCollector = { items: string[] };
+const OlCollectorContext = createContext<OlCollector | null>(null);
+
+// ---------------------------------------------------------------------------
+// ColSpecContext — tracks Th alignment per column for Table separator row
+// ---------------------------------------------------------------------------
+
+/**
+ * Alignment value for a GFM table column.
+ * 'left' → `:---`, 'center' → `:---:`, 'right' → `---:`, undefined → `---`.
+ */
+export type ColAlign = 'left' | 'center' | 'right';
+
+/**
+ * Mutable spec box passed through context during Table rendering.
+ * Th pushes its alignment (or undefined) into spec.cols; Table reads the
+ * array after the header row renders to build the GFM separator row.
+ */
+type ColSpec = { cols: Array<ColAlign | undefined> };
+const ColSpecContext = createContext<ColSpec | null>(null);
+
+function alignSeparator(align: ColAlign | undefined): string {
+  if (align === 'left') return ':---';
+  if (align === 'center') return ':---:';
+  if (align === 'right') return '---:';
+  return '---';
+}
 
 // ---------------------------------------------------------------------------
 // Block elements — trailing \n\n
@@ -102,34 +132,34 @@ interface BlockProps {
 }
 
 export function H1({ children }: BlockProps): string {
-  return `# ${render(children ?? null)}\n\n`;
+  return `# ${render(children).trim()}\n\n`;
 }
 
 export function H2({ children }: BlockProps): string {
-  return `## ${render(children ?? null)}\n\n`;
+  return `## ${render(children).trim()}\n\n`;
 }
 
 export function H3({ children }: BlockProps): string {
-  return `### ${render(children ?? null)}\n\n`;
+  return `### ${render(children).trim()}\n\n`;
 }
 
 export function H4({ children }: BlockProps): string {
-  return `#### ${render(children ?? null)}\n\n`;
+  return `#### ${render(children).trim()}\n\n`;
 }
 
 export function H5({ children }: BlockProps): string {
-  return `##### ${render(children ?? null)}\n\n`;
+  return `##### ${render(children).trim()}\n\n`;
 }
 
 export function H6({ children }: BlockProps): string {
-  return `###### ${render(children ?? null)}\n\n`;
+  return `###### ${render(children).trim()}\n\n`;
 }
 
 export function P({ children }: BlockProps): string {
-  return `${render(children ?? null)}\n\n`;
+  return `${render(children)}\n\n`;
 }
 
-export function Hr(): string {
+export function Hr(_: { children?: never } = {}): string {
   return '---\n\n';
 }
 
@@ -141,14 +171,16 @@ interface CodeblockProps {
 
 export function Codeblock({ lang = '', children, indent = 0 }: CodeblockProps): string {
   const prefix = ' '.repeat(indent);
-  const rawLines = render(children ?? null).split('\n');
+  const content = render(children);
+  const fence = '`'.repeat(backtickFenceLength(content, 3));
+  const rawLines = content.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`;
+  return `${fence}${lang}\n${body}\n${fence}\n\n`;
 }
 
 /**
@@ -162,7 +194,7 @@ export function Codeblock({ lang = '', children, indent = 0 }: CodeblockProps):
  * with `> `, producing `> > text`.
  */
 export function Blockquote({ children }: BlockProps): string {
-  const content = render(children ?? null).trimEnd();
+  const content = render(children).trimEnd();
   const lines = content.split('\n').map((line) => (line === '' ? '>' : `> ${line}`)).join('\n');
   return `${lines}\n\n`;
 }
@@ -173,49 +205,50 @@ export function Blockquote({ children }: BlockProps): string {
 
 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)),
+  // Clear OlCollectorContext so Li items inside a Ul nested within Ol
+  // render as "- " bullet items, not push to the outer Ol's collector.
+  const rendered = withContext(OlCollectorContext, null, () =>
+    withContext(DepthContext, depth + 1, () => render(children)),
   );
-  // Add trailing newline only at the outermost list level
-  return depth === 0 ? `${rendered}\n` : rendered;
+  // At depth 0 (outermost): trailing \n to form a block.
+  // At depth > 0 (nested): leading \n so the sublist starts on its own line
+  // when concatenated with the parent Li text.
+  return depth === 0 ? `${rendered}\n` : `\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.
+ * their indentation. When an OlCollector is present in context, Li pushes
+ * its content to collector.items and returns '' — Ol then numbers the
+ * collected items. This pattern supports Ol at any nesting depth, including
+ * Ol inside Ol, Ol inside Ul, etc.
  */
 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)),
+  const collector: OlCollector = { items: [] };
+  withContext(OlCollectorContext, collector, () =>
+    withContext(DepthContext, depth + 1, () => render(children)),
   );
-  let counter = 0;
-  return rendered.replace(/^\x01/gm, () => `${++counter}. `) + '\n';
+  const indent = '  '.repeat(depth);
+  const numbered = collector.items
+    .map((item, i) => `${indent}${i + 1}. ${item}`)
+    .join('');
+  return depth === 0 ? `${numbered}\n` : `\n${numbered}`;
 }
 
 export function Li({ children }: BlockProps): string {
   const depth = useContext(DepthContext);
-  const isInOl = useContext(OlContext);
+  const collector = useContext(OlCollectorContext);
   // 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`;
+  const inner = render(children).trimEnd();
+  if (collector) {
+    // Inside Ol: push content to collector; Ol will number items after rendering.
+    collector.items.push(`${inner}\n`);
+    return '';
   }
   return `${indent}- ${inner}\n`;
 }
@@ -228,33 +261,38 @@ export function Li({ children }: BlockProps): string {
  * 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.
+ *
+ * Th also increments the ColCountContext counter so Table knows how many
+ * columns the header row has without parsing pipe characters.
  */
-export function Th({ children }: { children?: VNode }): string {
-  return ` ${render(children ?? null)} |`;
+export function Th({ children, align }: { children?: VNode; align?: ColAlign }): string {
+  const spec = useContext(ColSpecContext);
+  if (spec) spec.cols.push(align);
+  return ` ${render(children)} |`;
 }
 
 export function Td({ children }: { children?: VNode }): string {
-  return ` ${render(children ?? null)} |`;
+  return ` ${render(children)} |`;
 }
 
 export function Tr({ children }: { children?: VNode }): string {
-  return `|${render(children ?? null)}\n`;
+  return `|${render(children)}\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.
+ * first row (the header). Column count is obtained from ColCountContext which
+ * Th increments during rendering — correct even when cells contain '|'.
  */
 export function Table({ children }: { children?: VNode }): string {
-  const rendered = render(children ?? null);
+  const spec: ColSpec = { cols: [] };
+  const rendered = withContext(ColSpecContext, spec, () => render(children));
   const lines = rendered.split('\n').filter((l) => l.trim().length > 0);
   if (lines.length === 0) {
     return '';
   }
+  const separator = '| ' + spec.cols.map(alignSeparator).join(' | ') + ' |';
   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';
 }
@@ -268,19 +306,43 @@ interface InlineProps {
 }
 
 export function Bold({ children }: InlineProps): string {
-  return `**${render(children ?? null)}**`;
+  const inner = render(children).replace(/\*\*/g, '\\*\\*');
+  return `**${inner}**`;
 }
 
 export function Code({ children }: InlineProps): string {
-  return `\`${render(children ?? null)}\``;
+  const inner = render(children);
+  const fence = '`'.repeat(backtickFenceLength(inner));
+  return `${fence}${inner}${fence}`;
 }
 
 export function Italic({ children }: InlineProps): string {
-  return `*${render(children ?? null)}*`;
+  return `*${render(children)}*`;
 }
 
 export function Strikethrough({ children }: InlineProps): string {
-  return `~~${render(children ?? null)}~~`;
+  const inner = render(children).replace(/~~/g, '\\~\\~');
+  return `~~${inner}~~`;
+}
+
+export function Br(_: { children?: never } = {}): string {
+  return '  \n';
+}
+
+export function Sup({ children }: InlineProps): string {
+  return `<sup>${render(children)}</sup>`;
+}
+
+export function Sub({ children }: InlineProps): string {
+  return `<sub>${render(children)}</sub>`;
+}
+
+export function Kbd({ children }: InlineProps): string {
+  return `<kbd>${render(children)}</kbd>`;
+}
+
+export function Escape({ children }: InlineProps): string {
+  return escapeMarkdown(render(children));
 }
 
 interface LinkProps {
@@ -289,7 +351,7 @@ interface LinkProps {
 }
 
 export function Link({ href, children }: LinkProps): string {
-  return `[${render(children ?? null)}](${encodeLinkUrl(href)})`;
+  return `[${render(children)}](${encodeLinkUrl(href)})`;
 }
 
 interface ImgProps {
@@ -306,7 +368,7 @@ export function Img({ src, alt = '' }: ImgProps): string {
 // ---------------------------------------------------------------------------
 
 export function Md({ children }: BlockProps): string {
-  return render(children ?? null);
+  return render(children);
 }
 
 // ---------------------------------------------------------------------------
@@ -315,9 +377,9 @@ export function Md({ children }: BlockProps): string {
 
 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;
+  const rendered = withContext(DepthContext, depth + 1, () => render(children));
+  // Mirror Ul: at depth 0 trailing \n, at depth > 0 leading \n
+  return depth === 0 ? `${rendered}\n` : `\n${rendered}`;
 }
 
 export function Task({ children, done }: { children?: VNode; done?: boolean }): string {
@@ -325,9 +387,7 @@ export function Task({ children, done }: { children?: VNode; done?: boolean }):
   // 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();
+  const inner = render(children).trimEnd();
   return `${indent}- ${prefix} ${inner}\n`;
 }
 
@@ -344,7 +404,7 @@ export function Callout({
   children?: VNode;
   type: CalloutType;
 }): string {
-  const inner = render(children ?? null).trimEnd();
+  const inner = render(children).trimEnd();
   const lines = inner.split('\n').map((line) => (line === '' ? '>' : `> ${line}`)).join('\n');
   return `> [!${type.toUpperCase()}]\n${lines}\n\n`;
 }
@@ -354,15 +414,19 @@ export function Callout({
 // ---------------------------------------------------------------------------
 
 export function HtmlComment({ children }: { children?: VNode }): string {
-  const inner = render(children ?? null).trimEnd();
+  const inner = render(children).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`;
+  // Sanitize in a single pass (left-to-right alternation):
+  // '-->': closes comment prematurely → replace '>' with ' >' to break the sequence
+  // '--': invalid per HTML spec → replace second '-' with ' -'
+  const safe = inner.replace(/-->|--/g, (m) => (m === '-->' ? '-- >' : '- -'));
+  if (safe.includes('\n')) {
+    return `<!--\n${safe}\n-->\n`;
   }
-  return `<!-- ${inner} -->\n`;
+  return `<!-- ${safe} -->\n`;
 }
 
 // ---------------------------------------------------------------------------
@@ -376,8 +440,10 @@ export function Details({
   children?: VNode;
   summary: string;
 }): string {
+  // Newlines in summary break the <summary> element — collapse to spaces.
+  const safeSummary = escapeHtmlContent(summary.replace(/\n/g, ' '));
   // 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`;
+  const body = render(children).trimEnd();
+  return `<details>\n<summary>${safeSummary}</summary>\n\n${body}\n\n</details>\n`;
 }

package/src/render.ts

@@ -5,13 +5,13 @@
  * 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.
+ * Fragment is a Symbol (imported from jsx-runtime.ts). When render() encounters
+ * a VNodeElement whose type is the Fragment symbol, it renders children directly.
+ * This keeps the dependency one-way (render.ts → jsx-runtime.ts) with no cycle.
  */
 
-import { registerRender } from './_render-registry.ts';
 import { escapeHtmlAttr } from './escape.ts';
-import { type VNode, type VNodeElement } from './jsx-runtime.ts';
+import { Fragment, type VNode, type VNodeElement } from './jsx-runtime.ts';
 
 function isVNodeElement(node: VNode): node is VNodeElement {
   return typeof node === 'object' && node !== null && !Array.isArray(node);
@@ -25,37 +25,72 @@ export function render(node: VNode): string {
     return node;
   }
   if (typeof node === 'number') {
-    return String(node);
+    return Number.isFinite(node) ? String(node) : '';
   }
   if (Array.isArray(node)) {
-    return (node as ReadonlyArray<VNode>).map(render).join('');
+    return node.map(render).join('');
   }
   // VNodeElement — dispatch on type
   if (!isVNodeElement(node)) {
+    // From TypeScript's perspective this branch is unreachable: after the null/boolean/string/
+    // number/Array guards above, the only remaining VNode member is VNodeElement, so `node`
+    // is already narrowed to VNodeElement and `!isVNodeElement` is statically false.
+    // The branch is kept as a runtime-only defensive net: if a caller bypasses TypeScript
+    // (plain JS, `as any`, etc.) and passes a function as a child, we throw a diagnostic
+    // error instead of silently returning ''. The double-cast (`as unknown as fn`) is
+    // required precisely because TS knows this is unreachable.
+    if (typeof node === 'function') {
+      throw new Error(
+        `jsx-md: a function was passed as a VNode child. Did you forget to call it, or wrap it in JSX? ` +
+          `Received: ${(node as unknown as (...args: unknown[]) => unknown).name || 'anonymous function'}`,
+      );
+    }
     return '';
   }
   const el = node; // narrowed to VNodeElement
 
+  // Fragment symbol — render children directly
+  if (el.type === Fragment) {
+    // props is Record<string, unknown> by design (props type varies per-component and cannot
+    // be narrowed at the VNodeElement level). The `as VNode` cast is safe in practice: the
+    // only source of props.children values is the JSX compiler and user JSX expressions,
+    // both of which TypeScript has already validated as VNode at the call site.
+    return render(el.props.children as VNode ?? null);
+  }
+
   // String type → render as an XML block tag
   if (typeof el.type === 'string') {
+    const tagName = el.type;
+    if (!/^[a-zA-Z][a-zA-Z0-9:._-]*$/.test(tagName)) {
+      throw new Error(
+        `jsx-md: invalid XML tag name "${tagName}". Tag names must start with a letter and contain only letters, digits, ':', '.', '_', or '-'.`,
+      );
+    }
     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('');
+    let attrStr = '';
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v === undefined || v === null || v === false) continue;
+      if (v === true) {
+        attrStr += ` ${k}`;
+      } else if (typeof v === 'object') {
+        throw new Error(
+          `jsx-md: attribute "${k}" received an object value. XML attributes must be strings. ` +
+            `Use JSON.stringify() to convert: ${k}={JSON.stringify(v)}`,
+        );
+      } else {
+        attrStr += ` ${k}="${escapeHtmlAttr(String(v))}"`;
+      }
+    }
+    // Same cast rationale as the Fragment branch above: props.children is unknown
+    // at the VNodeElement level but is guaranteed VNode by the JSX type system.
     const inner = render(children as VNode ?? null);
-    if (inner === '') {
-      return `<${el.type}${attrStr} />\n`;
+    if (inner.trimEnd() === '') {
+      return `<${tagName}${attrStr} />\n`;
     }
-    return `<${el.type}${attrStr}>\n${inner.trimEnd()}\n</${el.type}>\n`;
+    return `<${tagName}${attrStr}>\n${inner.trimEnd()}\n</${tagName}>\n`;
   }
 
   // Function component — call with its props (children still as VNode),
-  // then recurse in case the component returned a VNode (e.g. a Fragment).
+  // then recurse in case the component returned a VNode.
   return render(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);

package/src/_render-registry.ts

@@ -1,16 +0,0 @@
-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);
-}