@lincyaw/viewer 0.0.0-stage → 1.0.0-rc.1

package/src/client/code/outputs.ts

@@ -0,0 +1,84 @@
+import { currentLocale } from '@lincyaw/host'
+import { htmlAsText, isProseRun } from '@lincyaw/kernel'
+import type { MdastNode, RunOutput, RunResult } from '@lincyaw/kernel'
+import { AnsiUp } from 'ansi_up'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { gfmFromMarkdown } from 'mdast-util-gfm'
+import { gfm } from 'micromark-extension-gfm'
+import type { ReactElement, ReactNode } from 'react'
+import { useEffect, useState } from 'react'
+import { h } from '../element.ts'
+import { outputNotes } from '../../domain/index.ts'
+import { markdownToHast } from '../markdown/handlers.ts'
+import { PmMath } from '../markdown/math.ts'
+import { hastToVNodes } from '../markdown/render.ts'
+import { findNodeRenderer } from '../registry.ts'
+
+const ORDER = ['text/html', 'text/markdown', 'text/latex', 'image/svg+xml', 'image/png', 'image/jpeg', 'image/gif', 'application/json', 'text/plain']
+
+function text(value: unknown): string {
+  return Array.isArray(value) ? value.join('') : typeof value === 'string' ? value : JSON.stringify(value, null, 2)
+}
+
+function ansi(value: string): string {
+  return new AnsiUp().ansi_to_html(value)
+}
+
+function markdownOutput(markdown: string, prefix: string): ReactNode[] {
+  const mdast = htmlAsText(fromMarkdown(markdown, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] }) as unknown as MdastNode)
+  return hastToVNodes(markdownToHast(mdast, prefix).children, {})
+}
+
+let purify: Promise<(html: string) => string> | undefined
+
+function HtmlOutput({ html, plain = '' }: { html: string, plain?: string }) {
+  const [clean, setClean] = useState<string>()
+  useEffect(() => { let active = true; purify ??= import('dompurify').then(m => (html: string) => m.default.sanitize(html)); void purify.then(sanitize => { if (active) setClean(sanitize(html)) }); return () => { active = false } }, [html])
+  return clean === undefined ? h('pre', { className: 'pm-output__text' }, plain) : h('div', { className: 'pm-output__html', innerHTML: clean })
+}
+
+function display(data: Record<string, unknown>, metadata: Record<string, unknown>, prefix: string, key: number): ReactNode {
+  for (const type of Object.keys(data)) {
+    const renderer = findNodeRenderer(`mime:${type}`)
+    if (renderer) return h(renderer, { key, type, data: data[type], metadata })
+  }
+  const type = ORDER.find(t => data[t] !== undefined)
+  if (!type) return null
+  const value = data[type]
+  const attrs = { 'key': key, 'class': 'pm-output__display', 'data-mime': type }
+  if (type === 'text/html') return h('div', attrs, [h(HtmlOutput, { html: text(value), plain: text(data['text/plain'] ?? '') })])
+  if (type === 'text/markdown') return h('div', { ...attrs, class: ['pm-output__display', 'pm-output__markdown'] }, markdownOutput(text(value), prefix))
+  if (type === 'text/latex') return h('div', attrs, [h(PmMath, { tex: text(value).trim().replace(/^\$\$?|\$\$?$/g, ''), display: true })])
+  if (type === 'image/svg+xml') return h('div', attrs, [h('img', { src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(text(value))}`, alt: '' })])
+  if (type.startsWith('image/')) return h('div', attrs, [h('img', { src: `data:${type};base64,${text(value).replace(/\s/g, '')}`, alt: '' })])
+  if (type === 'application/json') return h('pre', attrs, JSON.stringify(value, null, 2))
+  return h('pre', { ...attrs, innerHTML: ansi(text(value)) })
+}
+
+function richOutput(output: RunOutput, prefix: string, key: number): ReactNode {
+  switch (output.output_type) {
+    case 'stream': return h('pre', { key, class: `pm-output__${output.name}`, innerHTML: ansi(text(output.text)) })
+    case 'error': return h('pre', { key, class: 'pm-output__error', innerHTML: ansi(text(output.traceback.join('\n')) || `${output.ename}: ${output.evalue}`) })
+    default: return display(output.data, output.metadata ?? {}, prefix, key)
+  }
+}
+
+/** Whether a run only displays Markdown that no plugin renders itself, which shows as prose. */
+export function isProseOutput(run: RunResult): boolean {
+  return isProseRun(run, type => Boolean(findNodeRenderer(`mime:${type}`)))
+}
+
+export function runOutput(run: RunResult & { cacheKey?: string }, key: string | number, prefix: string, options: { prose?: boolean, note?: string } = {}): ReactElement {
+  const notes = [...outputNotes(run, currentLocale()), ...options.note ? [options.note] : []]
+  const content = run.outputs
+    ? run.outputs.map((output, i) => richOutput(output, prefix, i))
+    : [
+        run.stdout ? h('pre', { class: 'pm-output__stdout' }, run.stdout) : null,
+        run.stderr ? h('pre', { class: 'pm-output__stderr' }, run.stderr) : null,
+      ]
+  if (options.prose) return h('div', { 'key': key, 'class': 'pm-output pm-output--prose', 'data-executor': run.executorId }, content)
+  return h('div', { 'key': key, 'class': ['pm-output', { 'pm-output--failed': !run.ok }], 'data-executor': run.executorId }, [
+    ...content,
+    notes.length ? h('p', { class: 'pm-output__note' }, notes.join(' · ')) : null,
+  ])
+}

package/src/client/content-marks.ts

@@ -0,0 +1,15 @@
+import { PmIcon } from '@lincyaw/host'
+import type { IRSection } from '@lincyaw/kernel'
+import { h } from './element.ts'
+import { viewerMessages } from './viewer-messages.ts'
+
+/** Author controls are excluded by the preview's text reader and are hidden outside document editing. */
+export function contentMarks(section: IRSection, role: 'visual' | 'narration' | 'reading', at: number, span = 0) {
+  const label = viewerMessages().contentRoles[role]
+  const place = `${section.index} · ${at + 1}${span > 0 ? `–${at + span + 1}` : ''}`
+  return h('span', { class: 'pm-content-marks', contenteditable: 'false', 'data-preview-ui': '' }, [h('button', {
+    'type': 'button', 'class': 'pm-content-mark',
+    'data-content-section': section.id, 'data-content-step': at,
+    'title': `${label} · ${place}`, 'aria-label': `${label} · ${place}`,
+  }, [h(PmIcon, { name: role === 'visual' ? 'slides' : role === 'reading' ? 'notebook' : 'captions' }), h('span', place)])])
+}

package/src/client/element.ts

@@ -0,0 +1,27 @@
+import { createElement, isValidElement } from 'react'
+import type { ElementType, ReactElement, ReactNode } from 'react'
+import styleToJs from 'style-to-js'
+export function classNames(value: unknown): string | undefined {
+  if (!value) return undefined
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) return value.map(classNames).filter(Boolean).join(' ')
+  if (typeof value === 'object') return Object.entries(value).filter(([, active]) => active).map(([key]) => key).join(' ')
+  return undefined
+}
+/** Shared DOM attribute normalization for HAST and the viewer's generated elements. */
+export function h(type: ElementType | any, attrs?: Record<string, any> | ReactNode | null, children?: ReactNode, ...rest: ReactNode[]): ReactElement {
+  if (attrs !== null && attrs !== undefined && (typeof attrs !== 'object' || Array.isArray(attrs) || isValidElement(attrs))) return createElement(type, null, attrs as ReactNode, children, ...rest)
+  const props = { ...attrs as Record<string, any> }
+  if (typeof props.style === 'string') {
+    try { props.style = styleToJs(props.style, { reactCompat: true }) }
+    catch {
+      props.style = {}
+      console.warn('[presmium.viewer.style] Invalid inline style was ignored; content is preserved.')
+    }
+  }
+  if (props.class !== undefined) { props.className = classNames(props.class); delete props.class }
+  if (props.innerHTML !== undefined) { props.dangerouslySetInnerHTML = { __html: props.innerHTML }; delete props.innerHTML }
+  if (props.tabindex !== undefined) { props.tabIndex = props.tabindex; delete props.tabindex }
+  if (props.contenteditable !== undefined) { props.contentEditable = props.contenteditable; delete props.contenteditable }
+  return createElement(type, props, children, ...rest)
+}

package/src/client/env.d.ts

@@ -0,0 +1,3 @@
+interface ImportMetaEnv {
+  SSR: boolean
+}

package/src/client/index.ts

@@ -0,0 +1,40 @@
+import { createElement } from 'react'
+import type { ReactNode } from 'react'
+import { registerAction, registerComponent, registerView } from './registry.ts'
+import { DOCUMENT_LAYOUT_COMPONENTS } from './layout.ts'
+import { viewerMessages } from './viewer-messages.ts'
+import { VIEWER } from './viewer-state.ts'
+import type { Viewer } from './viewer-state.ts'
+import { BUILTIN_ACTIONS } from './views/actions.ts'
+import { DocumentView } from './views/document.ts'
+import { PresentView } from './views/present.ts'
+import { PresenterView } from './views/presenter.ts'
+import { ScrollyView } from './views/scrolly.ts'
+import './style.css'
+
+registerView({ id: 'document', get label() { return viewerMessages().views.document }, kind: 'page', component: DocumentView })
+registerView({ id: 'scrolly', get label() { return viewerMessages().views.scrolly }, kind: 'page', component: ScrollyView })
+registerView({ id: 'present', get label() { return viewerMessages().views.present }, kind: 'overlay', component: PresentView })
+registerView({ id: 'presenter', get label() { return viewerMessages().views.presenter }, kind: 'overlay', component: PresenterView, hidden: true })
+BUILTIN_ACTIONS.forEach(registerAction)
+Object.entries(DOCUMENT_LAYOUT_COMPONENTS).forEach(([name, component]) => registerComponent(name, component))
+
+export function ViewerProvider({ viewer, children }: { viewer: Viewer, children?: ReactNode }) { return createElement(VIEWER.Provider, { value: viewer }, children) }
+
+export { BlockView, BlockPreview, PmComponentFallback } from './block.ts'
+export { syncViewerWithOperations } from './operations.ts'
+export { findView, findComponent, listViews, registerComponent, registryRevision } from './registry.ts'
+export type { NodeRenderer, ViewDefinition, ViewerAction, ViewerLayer } from './registry.ts'
+export { SectionView } from './section.ts'
+export type { SectionLayout } from './section.ts'
+export { useSectionContext } from './section-context.ts'
+export type { SectionContext } from './section-context.ts'
+export { withSlideGlobals } from './slidev-compat/slide-globals.ts'
+export { tryInstallViewerPlugin } from './viewer-plugins.ts'
+export type { ViewerPlugin, ViewerPluginContext } from './viewer-plugins.ts'
+export { createViewer, useViewer } from './viewer-state.ts'
+export type { Viewer, ViewerOptions } from './viewer-state.ts'
+export { OverlayViewOutlet, PageViewOutlet } from './views/outlets.ts'
+export { SlideFace, SlideFit, SlidesPrint } from './views/slide.ts'
+
+export { VClick, VAfter, VClicks } from "./slidev-compat/click-directives.ts"

package/src/client/layout.ts

@@ -0,0 +1,22 @@
+import { Children, createElement as h, isValidElement } from 'react'
+import type { ReactNode } from 'react'
+import { PmColumns, PmStack, PmTabGroup, useMessages, useStaticRender } from '@lincyaw/host'
+import type { ContentLayoutProps } from '@lincyaw/host'
+import { blockVisible } from '@lincyaw/kernel'
+import type { BlockProps } from './block.ts'
+import { FINAL_STEP } from '../domain/index.ts'
+import { useSectionContext } from './section-context.ts'
+
+const MESSAGES = { 'zh-CN': { tabs: '分组内容', item: (index: number) => `内容 ${index}` }, en: { tabs: 'Grouped content', item: (index: number) => `Content ${index}` } }
+function LayoutTabs({ title, tabTitles, children }: ContentLayoutProps & { tabTitles?: string[] }) {
+  const t = useMessages(MESSAGES), printed = useStaticRender(), section = useSectionContext()
+  const tabs = Children.toArray(children).map((content, index) => {
+    const props = isValidElement<BlockProps>(content) ? content.props : undefined
+    return { id: props?.block?.id ?? String(index), title: tabTitles?.[index] || t.item(index + 1), content,
+      visible: !props?.block || props.expanded || blockVisible(props.block, section?.step ?? FINAL_STEP) }
+  })
+  return h(PmTabGroup, { title, label: t.tabs, tabs, staticView: printed })
+}
+
+/** Layout nodes are part of the document runtime and need no separately installed plugin. */
+export const DOCUMENT_LAYOUT_COMPONENTS = { PmColumns, PmStack, PmTabs: LayoutTabs }

package/src/client/markdown/handlers.ts

@@ -0,0 +1,161 @@
+import { isButton, roleMark, safeDecodeURIComponent, urlSlug } from '@lincyaw/kernel'
+import type { MdastNode } from '@lincyaw/kernel'
+import type { Element, ElementContent, Nodes, Root } from 'hast'
+import { raw } from 'hast-util-raw'
+import type { Handler, Handlers, State } from 'mdast-util-to-hast'
+import { defaultHandlers, toHast } from 'mdast-util-to-hast'
+import { viewerMessages } from '../viewer-messages.ts'
+import { footnoteId } from '../viewer-state.ts'
+import type { Viewer } from '../viewer-state.ts'
+import { classed, classes, element, text } from './hast.ts'
+import { layoutHandlers } from './layout-handlers.ts'
+import { tabHandlers } from './tabs.ts'
+import { tableHandler } from './tables.ts'
+
+export interface MarkdownLinks {
+  footnoteHref?(identifier: string): string
+  section?(id: string): { href: string, title: string } | undefined
+}
+
+export function viewerLinks(viewer: Viewer | undefined): MarkdownLinks {
+  if (!viewer) return {}
+  return {
+    footnoteHref: viewer.footnoteHref,
+    section(id) {
+      const section = viewer.section(id)
+      return section && { href: viewer.options.sectionHref?.(id) ?? `#${id}`, title: section.title }
+    },
+  }
+}
+
+/** The nodes the viewer renders with its own components; they pass through the HAST tree untouched. */
+export type ViewerNode =
+  | { type: 'pmMath', tex: string, display: boolean, html?: string }
+  | { type: 'pmMermaid', code: string }
+  | { type: 'pmCode', lang: string, code: string }
+  | { type: 'pmRole', mark: string }
+
+const VIEWER_NODES: ViewerNode['type'][] = ['pmMath', 'pmMermaid', 'pmCode', 'pmRole']
+
+function viewerNode(node: ViewerNode): ElementContent {
+  return node as unknown as ElementContent
+}
+
+export function asViewerNode(node: { type: string }): ViewerNode | undefined {
+  return (VIEWER_NODES as string[]).includes(node.type) ? node as ViewerNode : undefined
+}
+
+const BLOCK_ELEMENTS = new Set([
+  'address', 'article', 'aside', 'blockquote', 'details', 'div', 'dl', 'dt', 'dd', 'fieldset', 'figcaption', 'figure', 'footer',
+  'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'iframe', 'li', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'table', 'ul',
+])
+
+function isBlock(node: ElementContent): boolean {
+  const own = asViewerNode(node)
+  if (own) return own.type === 'pmMermaid' || own.type === 'pmCode' || (own.type === 'pmMath' && own.display)
+  return node.type === 'element' && BLOCK_ELEMENTS.has(node.tagName)
+}
+
+function unknown(state: State, node: MdastNode): ElementContent | undefined {
+  if (!node.children) return typeof node.value === 'string' ? text(node.value) : undefined
+  const children = state.all(node as never)
+  return element(children.some(isBlock) ? 'div' : 'span', {}, children)
+}
+
+function handlers(links: MarkdownLinks): Handlers {
+  const footnoteHref = links.footnoteHref ?? ((identifier: string) => `#${footnoteId(identifier)}`)
+  const wrap = (tagName: string, className?: string): Handler => (state, node) =>
+    element(tagName, className ? { className: [className] } : {}, state.all(node))
+  const value = (node: { value?: unknown }) => (typeof node.value === 'string' ? node.value : '')
+  const identifier = (node: { identifier?: unknown, label?: unknown }) => String(node.identifier ?? node.label)
+  const label = (node: { identifier?: unknown, label?: unknown }) => String(node.label ?? node.identifier)
+  const footnoteMark = (node: { identifier?: unknown, label?: unknown, enumerator?: unknown }) => (node.enumerator !== undefined ? String(node.enumerator) : label(node))
+  const math = (node: MdastNode, display: boolean) => viewerNode({ type: 'pmMath', tex: value(node), display, html: typeof node.html === 'string' ? node.html : undefined })
+  const reference = (el: Element, id: string, fallback: string): Element => {
+    const target = id ? links.section?.(id) : undefined
+    if (target) el.properties.href = target.href
+    if (el.children.length === 0) el.children = [text(target?.title ?? fallback)]
+    return el
+  }
+  const custom: Record<string, Handler> = {
+    table: tableHandler,
+    math: (_, node) => math(node, true),
+    inlineMath: (_, node) => math(node, false),
+    mermaid: (_, node) => viewerNode({ type: 'pmMermaid', code: value(node) }),
+    code: (_, node) => viewerNode({ type: 'pmCode', lang: typeof node.lang === 'string' ? node.lang : '', code: value(node) }),
+    iframe: (_, node) => element('iframe', {
+      src: typeof node.src === 'string' ? node.src : '',
+      width: node.width == null || node.width === '' ? undefined : String(node.width),
+      height: node.height == null || node.height === '' ? undefined : String(node.height),
+      loading: 'lazy',
+    }),
+    admonition(state, node) {
+      const names = viewerMessages().markdown.admonitions
+      const extra = classes(node)
+      const kind = typeof node.kind === 'string' ? node.kind : extra.find(c => c in names) ?? 'note'
+      const children = state.all(node)
+      const titled = (node.children as MdastNode[] | undefined)?.some(c => c.type === 'admonitionTitle')
+      const title = titled ? [] : [element('p', { className: ['pm-admonition__title'] }, [text(names[kind] ?? kind)])]
+      return element('aside', { className: [...new Set(['pm-admonition', `pm-admonition--${kind}`, ...extra])] }, [...title, ...children])
+    },
+    admonitionTitle: wrap('p', 'pm-admonition__title'),
+    footnoteReference: (_, node) => element('sup', { className: ['pm-footnote-ref'] }, [
+      element('a', { href: footnoteHref(identifier(node)), dataLabel: footnoteMark(node), ariaLabel: viewerMessages().markdown.footnote(footnoteMark(node)) }, []),
+    ]),
+    footnoteDefinition: (state, node) => element('div', { id: footnoteId(identifier(node)), className: ['pm-footnote'] }, [
+      element('sup', { dataLabel: footnoteMark(node) }, []),
+      ...state.all(node),
+    ]),
+    container: (state, node) => element('figure', { id: typeof node.identifier === 'string' ? node.identifier : undefined, className: ['pm-figure'] }, state.all(node)),
+    caption: wrap('figcaption'),
+    legend: wrap('div', 'pm-legend'),
+    abbreviation: (state, node) => element('abbr', typeof node.title === 'string' ? { title: node.title } : {}, state.all(node)),
+    crossReference: (state, node) => reference(element('a', { href: `#${identifier(node)}` }, state.all(node)), identifier(node), label(node)),
+    link(state, node) {
+      const el = defaultHandlers.link(state, node as never)
+      if (isButton(node)) el.properties.className = ['pm-button']
+      const url = typeof node.url === 'string' ? node.url : ''
+      return url.startsWith('#') ? reference(el, safeDecodeURIComponent(url.slice(1)), url.slice(1)) : reference(el, '', url)
+    },
+    keyboard: wrap('kbd'),
+    subscript: wrap('sub'),
+    superscript: wrap('sup'),
+    underline: wrap('u'),
+    definitionList: wrap('dl'),
+    definitionTerm: wrap('dt'),
+    definitionDescription: wrap('dd'),
+    details: (state, node) => element('details', classed(node, { open: node.open === true }), state.all(node)),
+    summary: wrap('summary'),
+    div: (state, node) => element('div', classed(node), state.all(node)),
+    span: (state, node) => element('span', isButton(node) ? { className: ['pm-button'] } : classed(node), state.all(node)),
+    ...layoutHandlers(),
+    ...tabHandlers(),
+    presmiumRole(state, node) {
+      const children = state.all(node)
+      return children.length
+        ? element('span', { className: ['pm-role'], dataRole: String(node.name ?? '') }, children)
+        : viewerNode({ type: 'pmRole', mark: roleMark(node) })
+    },
+  }
+  return custom as Handlers
+}
+
+function textOf(node: ElementContent | Root): string {
+  if (node.type === 'text') return node.value
+  return 'children' in node ? node.children.map(c => textOf(c as ElementContent)).join('') : ''
+}
+
+export function markdownToHast(mdast: MdastNode, prefix: string, links: MarkdownLinks = {}): Root {
+  const html = toHast(mdast as never, { allowDangerousHtml: true, handlers: handlers(links), unknownHandler: unknown as never }) as Nodes
+  const tree = raw(html, { passThrough: VIEWER_NODES }) as Root
+  let item = 0
+  for (const child of tree.children) {
+    if (child.type !== 'element') continue
+    if (/^h[1-6]$/.test(child.tagName) && child.properties.id === undefined) child.properties.id = `${prefix}-${urlSlug(textOf(child))}`
+    if (child.tagName !== 'ul' && child.tagName !== 'ol') continue
+    for (const li of child.children) {
+      if (li.type === 'element' && li.tagName === 'li') li.properties.dataPmItem = item++
+    }
+  }
+  return tree
+}

package/src/client/markdown/hast.ts

@@ -0,0 +1,20 @@
+import type { MdastNode } from '@lincyaw/kernel'
+import type { Element, ElementContent, Properties } from 'hast'
+
+export function element(tagName: string, properties: Properties, children: ElementContent[] = []): Element {
+  return { type: 'element', tagName, properties, children }
+}
+
+export function text(value: string): ElementContent {
+  return { type: 'text', value }
+}
+
+/** The classes a MyST node names in its `class` option. */
+export function classes(node: MdastNode): string[] {
+  return typeof node.class === 'string' ? node.class.split(/\s+/).filter(Boolean) : []
+}
+
+export function classed(node: MdastNode, properties: Properties = {}): Properties {
+  const names = classes(node)
+  return names.length ? { ...properties, className: names } : properties
+}

package/src/client/markdown/layout-handlers.ts

@@ -0,0 +1,57 @@
+import type { MdastNode } from '@lincyaw/kernel'
+import type { ElementContent } from 'hast'
+import type { Handler, State } from 'mdast-util-to-hast'
+import { classes, element } from './hast.ts'
+
+const WIDTHS = ['xs', 'sm', 'md', 'lg'] as const
+
+function gridColumns(node: MdastNode): number[] {
+  const given = Array.isArray(node.columns) ? node.columns.map(Number).filter(n => Number.isInteger(n) && n >= 1) : []
+  return WIDTHS.map((_, i) => given[Math.min(i, given.length - 1)] ?? 1)
+}
+
+const style = (values: Record<string, number>) => Object.entries(values).map(([key, value]) => `${key}: ${value}`).join('; ')
+
+const grid: Handler = (state, node: MdastNode) => {
+  const columns = gridColumns(node)
+  const children = state.all(node as never).map((child) => {
+    const twelfths = child.type === 'element' ? Number(child.properties.dataPmColumns) : Number.NaN
+    if (child.type !== 'element' || !(twelfths >= 1)) return child
+    const spans = Object.fromEntries(WIDTHS.map((width, i) => [`--pm-span-${width}`, Math.min(columns[i]!, Math.max(1, Math.round(twelfths * columns[i]! / 12)))]))
+    return { ...child, properties: { ...child.properties, style: style(spans) } }
+  })
+  const widths = Object.fromEntries(WIDTHS.map((width, i) => [`--pm-grid-${width}`, columns[i]!]))
+  return element('div', { className: ['pm-grid', ...classes(node)], style: style(widths) }, children)
+}
+
+const gridItem: Handler = (state, node: MdastNode) =>
+  element('div', { className: ['pm-grid__item', ...classes(node)], dataPmColumns: typeof node.columns === 'number' ? node.columns : undefined }, state.all(node as never))
+
+const card: Handler = (state: State, node: MdastNode) => {
+  const items = node.children ?? []
+  const part = (type: string) => items.find(child => child.type === type)
+  const url = typeof node.url === 'string' && node.url ? node.url : undefined
+  const header = part('header')
+  const footer = part('footer')
+  const title = part('cardTitle')
+  const content: ElementContent[] = []
+  if (header) content.push(element('header', { className: ['pm-card__header'] }, state.all(header as never)))
+  if (title || url) {
+    const words: MdastNode[] = title?.children?.length ? title.children : [{ type: 'text', value: url ?? '' }]
+    const inner = url ? [state.one({ type: 'link', url, children: words } as never, node as never) as ElementContent] : state.all({ type: 'paragraph', children: words } as never)
+    content.push(element('p', { className: ['pm-card__title'] }, inner))
+  }
+  const body = items.filter(child => child !== header && child !== title && child !== footer)
+  content.push(element('div', { className: ['pm-card__body'] }, state.all({ type: 'root', children: body } as never)))
+  if (footer) content.push(element('footer', { className: ['pm-card__footer'] }, state.all(footer as never)))
+  return element('div', { className: ['pm-card', ...url ? ['pm-card--link'] : [], ...classes(node)] }, content)
+}
+
+/** The handlers of MyST's grids and cards. */
+export function layoutHandlers(): Record<string, Handler> {
+  return {
+    'grid': grid,
+    'grid-item': gridItem,
+    'card': card,
+  }
+}

package/src/client/markdown/math.ts

@@ -0,0 +1,10 @@
+import { useEffect, useState } from 'react'
+import { escapeHtml } from '@lincyaw/kernel'
+import { h } from '../element.ts'
+import 'katex/dist/katex.min.css'
+export function PmMath({ tex, display, html }: { tex: string, display?: boolean, html?: string }) {
+  const [rendered, setRendered] = useState<string>()
+  useEffect(() => { let active = true; if (!html) void import('katex').then(m => { if (active) setRendered(m.default.renderToString(tex, { displayMode: display, throwOnError: false })) }); return () => { active = false } }, [tex, display, html])
+  const output = html ?? rendered
+  return h(display ? 'div' : 'span', { className: `pm-math pm-math--${display ? 'display' : 'inline'}`, 'data-rendered': output ? '' : undefined, innerHTML: output ?? escapeHtml(tex) })
+}

package/src/client/markdown/mermaid.ts

@@ -0,0 +1,75 @@
+import { useAppearance } from '@lincyaw/host'
+import { errorMessage, escapeHtml } from '@lincyaw/kernel'
+import { useEffect, useState } from 'react'
+import { h } from '../element.ts'
+
+type Mermaid = typeof import('mermaid').default
+
+let mermaid: Promise<Mermaid> | undefined
+let diagrams = 0
+
+function loadMermaid(): Promise<Mermaid> {
+  if (import.meta.env.SSR) return new Promise(() => {})
+  mermaid ??= import('mermaid').then(m => m.default)
+  return mermaid
+}
+
+/** Mermaid's theme variables from the page's design tokens; undefined when the page has none. */
+function mermaidThemeVariables(dark: boolean): Record<string, string | boolean> | undefined {
+  const style = getComputedStyle(document.documentElement)
+  const colorToken = (name: string) => style.getPropertyValue(`--pm-color-${name}`).trim()
+  const [ink, muted, surface, sunk, line, accent, accentSoft, warn, warnSoft] = ['ink', 'muted', 'surface', 'sunk', 'line', 'accent', 'accent-soft', 'warn', 'warn-soft'].map(colorToken)
+  if (!ink || !surface || !accent) return undefined
+  return {
+    darkMode: dark,
+    background: surface,
+    fontFamily: style.getPropertyValue('--pm-font-sans').trim() || 'sans-serif',
+    textColor: ink,
+    lineColor: muted!,
+    primaryColor: accentSoft!,
+    primaryTextColor: ink,
+    primaryBorderColor: accent,
+    secondaryColor: sunk!,
+    secondaryTextColor: ink,
+    secondaryBorderColor: line!,
+    tertiaryColor: surface,
+    tertiaryTextColor: ink,
+    tertiaryBorderColor: line!,
+    edgeLabelBackground: surface,
+    clusterBkg: sunk!,
+    clusterBorder: line!,
+    titleColor: ink,
+    noteBkgColor: warnSoft!,
+    noteTextColor: ink,
+    noteBorderColor: warn!,
+    actorBkg: accentSoft!,
+    actorBorder: accent,
+    actorTextColor: ink,
+    signalColor: ink,
+    signalTextColor: ink,
+    labelBoxBkgColor: sunk!,
+    labelTextColor: ink,
+    loopTextColor: ink,
+  }
+}
+
+export function PmMermaid({ code }: { code: string }) {
+  const [drawn, setDrawn] = useState<{ svg: string, theme: string }>()
+  const [failed, setFailed] = useState<string>()
+  const { dark } = useAppearance()
+  useEffect(() => {
+    let active = true
+    void (async () => {
+      try {
+        const library = await loadMermaid()
+        const variables = mermaidThemeVariables(dark)
+        const appearance = dark ? 'dark' : 'default'
+        library.initialize({ startOnLoad: false, securityLevel: 'strict', theme: variables ? 'base' : appearance, ...variables ? { themeVariables: variables } : {}, flowchart: { useMaxWidth: false } })
+        const { svg } = await library.render(`pm-mermaid-${++diagrams}`, code)
+        if (active) { setDrawn({ svg, theme: appearance }); setFailed(undefined) }
+      } catch (error) { if (active) setFailed(errorMessage(error)) }
+    })()
+    return () => { active = false }
+  }, [code, dark])
+  return h('div', { className: `pm-mermaid${failed ? ' pm-mermaid--error' : ''}`, 'data-rendered': drawn ? '' : undefined, 'data-theme': drawn?.theme, title: failed, innerHTML: drawn?.svg ?? `<pre>${escapeHtml(code)}</pre>` })
+}

package/src/client/markdown/render.ts

@@ -0,0 +1,79 @@
+import { blockStepState } from '@lincyaw/kernel'
+import { currentLocale } from '@lincyaw/host'
+import type { IRBlock, MarkdownNode } from '@lincyaw/kernel'
+import type { ElementContent, Properties, RootContent } from 'hast'
+import { find, html as schema } from 'property-information'
+import type { ComponentType, ReactNode } from 'react'
+import { useContext } from 'react'
+import { useStore } from '@lincyaw/host'
+import { h } from '../element.ts'
+import { itemVisible } from '../../domain/index.ts'
+import { CodeView } from '../code/code-view.ts'
+import { VIEWER } from '../viewer-state.ts'
+import { asViewerNode, markdownToHast, viewerLinks } from './handlers.ts'
+import type { ViewerNode } from './handlers.ts'
+import { PmMath } from './math.ts'
+import { PmMermaid } from './mermaid.ts'
+import { PmRoleMark } from './role-mark.ts'
+import { tabEntries, TabSetView } from './tabs.ts'
+import { cachedTree } from './tree-cache.ts'
+
+function attributes(properties: Properties): Record<string, unknown> {
+  const attrs: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(properties)) {
+    if (value === null || value === undefined || value === false) continue
+    const info = find(schema, key)
+    attrs[info.attribute] = value === true ? (info.boolean ? true : '') : Array.isArray(value) ? value.join(info.commaSeparated ? ', ' : ' ') : value
+  }
+  return attrs
+}
+
+function viewerComponent(node: ViewerNode): [ComponentType<any>, Record<string, unknown>] {
+  switch (node.type) {
+    case 'pmMath': return [PmMath, { tex: node.tex, display: node.display, html: node.html }]
+    case 'pmMermaid': return [PmMermaid, { code: node.code }]
+    case 'pmCode': return [CodeView, { lang: node.lang, value: node.code }]
+    case 'pmRole': return [PmRoleMark, { mark: node.mark }]
+  }
+}
+
+export interface HastRenderContext {
+  hidden?(item: number): boolean
+}
+
+const RAW_TEXT = new Set(['script', 'style'])
+const VOID_ELEMENTS = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'])
+
+export function hastToVNodes(nodes: readonly (RootContent | ElementContent)[], ctx: HastRenderContext): ReactNode[] {
+  return nodes.map((node): ReactNode => {
+    const own = asViewerNode(node)
+    if (own) {
+      const [component, props] = viewerComponent(own)
+      return h(component, props)
+    }
+    if (node.type === 'text') return node.value
+    if (node.type !== 'element') return null
+    const attrs = attributes(node.properties)
+    const item = node.properties.dataPmItem
+    if (typeof item === 'number' && ctx.hidden?.(item)) attrs.class = [attrs.class, 'pm-hidden']
+    // HAST represents a void element with an empty children array. React treats
+    // even that array as children and refuses img/br/input before mounting.
+    if (VOID_ELEMENTS.has(node.tagName)) return h(node.tagName, attrs)
+    if (RAW_TEXT.has(node.tagName)) return h(node.tagName, { ...attrs, innerHTML: node.children.map(c => (c.type === 'text' ? c.value : '')).join('') })
+    if (node.properties.dataPmTabs !== undefined) {
+      return h(TabSetView, { class: attrs.class, tabs: tabEntries(node, children => hastToVNodes(children, ctx)) })
+    }
+    return h(node.tagName, attrs, hastToVNodes(node.children, ctx))
+  })
+}
+
+export function MarkdownView(props: { block: IRBlock, step: number, expanded?: boolean, prefix?: string }) {
+  const viewer = useContext(VIEWER)
+  const doc = useStore(viewer?.doc)
+  const links = viewerLinks(viewer)
+  const node = props.block.node as MarkdownNode
+  const tree = viewer && doc ? cachedTree(viewer, doc, node.mdast, props.prefix ?? '', links, currentLocale()) : markdownToHast(node.mdast, props.prefix ?? '', links)
+  const revealed = blockStepState(props.block, props.step)?.parameters?.revealedItems
+  const hidden = node.reveal === 'items' && !props.expanded ? (k: number) => typeof revealed === 'number' ? k >= revealed : !itemVisible(props.block, k, props.step) : undefined
+  return h('div', { className: 'pm-markdown' }, hastToVNodes(tree.children, { hidden }))
+}

package/src/client/markdown/role-mark.ts

@@ -0,0 +1,9 @@
+import { useEffect, useState } from 'react'
+import { AUTHOR_MARKS_CLASS } from '@lincyaw/kernel'
+import { useSectionContext } from '../section-context.ts'
+import { h } from '../element.ts'
+export function PmRoleMark({ mark }: { mark: string }) {
+  const section = useSectionContext(); const [shown, setShown] = useState(false)
+  useEffect(() => { const root = document.documentElement; const update = () => setShown(root.classList.contains(AUTHOR_MARKS_CLASS)); update(); const observer = new MutationObserver(update); observer.observe(root, { attributes: true, attributeFilter: ['class'] }); return () => observer.disconnect() }, [])
+  return shown || section?.view === 'presenter' ? h('span', { className: 'pm-role-mark' }, mark) : null
+}