@deckbuilderkit/editor 0.0.0-stage → 0.1.1

package/src/FilePreview.tsx

@@ -0,0 +1,108 @@
+import { type HighlightTerm, Icon, JsonTree, linesOf, LogView, PanelBanner, PanelLoading, PanelNotice, t } from '@deckbuilderkit/ui';
+import { lazy, Suspense, useMemo, useState } from 'react';
+import { type ArchiveContent, ArchiveView } from './ArchiveView';
+import { CodeView } from './CodeView';
+import { EnvView } from './EnvView';
+import { HarView } from './HarView';
+import { HexView } from './HexView';
+import { HtmlPreview } from './HtmlPreview';
+import { langOfFile, previewKind } from './languages';
+import { MarkdownView } from './MarkdownView';
+import { MediaView } from './MediaView';
+import { NotebookView } from './NotebookView';
+import { type SqliteContent, SqliteView } from './SqliteView';
+import type { ImageInfo } from './SvgView';
+import { TableView } from './TableView';
+
+export type { ImageInfo } from './SvgView';
+const SvgView = lazy(() => import('./SvgView').then((m) => ({ default: m.SvgView })));
+const PdfView = lazy(() => import('./PdfView').then((m) => ({ default: m.PdfView })));
+const FontView = lazy(() => import('./FontView').then((m) => ({ default: m.FontView })));
+
+/** `/api/fs/read` gives text or `{ binary }`; images come as a URL (a blob URL of `/api/fs/raw`). */
+export type PreviewContent = { text: string; truncated?: boolean } | { binary: true } | { url: string; source?: string } | { pdf: Uint8Array } | { archive: ArchiveContent }
+  | { bytes: Uint8Array } | { sqlite: SqliteContent; load(table: string, offset: number): Promise<SqliteContent> };
+
+/** Shows a file by its extension: rendered markdown, a JSON tree, highlighted code, a log, an image or plain text. */
+export function FilePreview({ name, content, resolveImage, viewHtml, onImageInfo, toc = true }: {
+  name: string;
+  content: PreviewContent;
+  resolveImage?(src: string): string | null;
+  /** URL the sandboxed frame of an HTML page loads, so its scripts and relative files work; without it the text is shown with scripts blocked. */
+  viewHtml?(): Promise<string>;
+  /** An image's size and zoom, for a status bar. */
+  onImageInfo?(info: ImageInfo): void;
+  /** Show the heading rail on rendered markdown; default on. */
+  toc?: boolean;
+}) {
+  const kind = previewKind(name);
+
+  if ('binary' in content) return <PanelNotice icon={<Icon name="cube" size={20} />} title={t('preview.binary')} />;
+  if ('archive' in content) return <ArchiveView archive={content.archive} />;
+  if ('pdf' in content) return <Suspense fallback={<PanelLoading />}><PdfView data={content.pdf} /></Suspense>;
+  if ('sqlite' in content) return <SqliteView content={content.sqlite} load={content.load} />;
+  if ('bytes' in content) {
+    return kind === 'font'
+      ? <Suspense fallback={<PanelLoading />}><FontView data={content.bytes} /></Suspense>
+      : <HexView bytes={content.bytes} />;
+  }
+  if ('url' in content) {
+    if (kind === 'audio' || kind === 'video') return <MediaView url={content.url} video={kind === 'video'} />;
+    if (kind !== 'svg' && kind !== 'image') return <PanelNotice icon={<Icon name="cube" size={20} />} title={t('preview.none')} message={t('preview.noneMessage')} />;
+    return <Suspense fallback={<PanelLoading />}><SvgView url={content.url} source={kind === 'svg' ? content.source : undefined} name={name} onInfo={onImageInfo} /></Suspense>;
+  }
+  return (
+    <div className="file-preview">
+      {content.truncated && <PanelBanner tone="warn" icon="alert">{t('preview.truncated')}</PanelBanner>}
+      {kind === 'markdown' ? <MarkdownPreview text={content.text} resolveImage={resolveImage} toc={toc} />
+        : kind === 'table' ? <TableView name={name} text={content.text} />
+          : kind === 'notebook' ? <NotebookView text={content.text} />
+            : kind === 'har' ? <HarView text={content.text} />
+              : kind === 'env' ? <EnvView text={content.text} />
+        : kind === 'html' ? <div className="file-preview-body"><HtmlPreview name={name} text={content.text} viewHtml={viewHtml} /></div>
+        : kind === 'json' ? <JsonPreview text={content.text} />
+          : kind === 'log' ? <LogPreview text={content.text} />
+          : <div className="file-preview-body"><CodeView value={content.text} lang={kind === 'code' ? langOfFile(name) : 'text'} lineNumbers /></div>}
+    </div>
+  );
+}
+
+function MarkdownPreview({ text, resolveImage, toc }: { text: string; resolveImage?(src: string): string | null; toc: boolean }) {
+  const [source, setSource] = useState(false);
+  return (
+    <>
+      <div className="file-preview-bar">
+        <button className="btn btn-ghost btn-sm" onClick={() => setSource(!source)} aria-pressed={source}>
+          {source ? t('preview.rendered') : t('preview.source')}
+        </button>
+      </div>
+      <div className="file-preview-body">
+        {source ? <CodeView value={text} lang="markdown" wrap lineNumbers /> : <MarkdownView markdown={text} resolveImage={resolveImage} toc={toc} />}
+      </div>
+    </>
+  );
+}
+
+/** A read-only LogView of the text: no follow, no bookmarks. */
+function LogPreview({ text }: { text: string }) {
+  const lines = useMemo(() => linesOf({ from: 0, to: 0, text }, 0, null), [text]);
+  const [highlights, setHighlights] = useState<HighlightTerm[]>([]);
+  return <div className="file-preview-body file-preview-log"><LogView lines={lines} highlights={highlights} onHighlightsChange={setHighlights} /></div>;
+}
+
+function JsonPreview({ text }: { text: string }) {
+  const parsed = useMemo(() => {
+    try {
+      return { value: JSON.parse(text) as unknown };
+    } catch (err) {
+      return { error: (err as Error).message };
+    }
+  }, [text]);
+  if ('value' in parsed) return <div className="file-preview-body"><JsonTree value={parsed.value} /></div>;
+  return (
+    <>
+      <PanelBanner tone="err">{t('preview.jsonError', { message: parsed.error })}</PanelBanner>
+      <div className="file-preview-body"><CodeView value={text} lang="json" lineNumbers /></div>
+    </>
+  );
+}

package/src/FontView.tsx

@@ -0,0 +1,48 @@
+import { PanelBanner, t } from '@deckbuilderkit/ui';
+import { useEffect, useState } from 'react';
+
+const SIZES = [12, 16, 24, 36, 56];
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ\nabcdefghijklmnopqrstuvwxyz\n0123456789 !?&@#$%(){}[]';
+
+let counter = 0;
+
+/** A font file shown at several sizes with editable sample text. */
+export function FontView({ data }: { data: Uint8Array }) {
+  const [family, setFamily] = useState<string>();
+  const [failed, setFailed] = useState(false);
+  const [sample, setSample] = useState(() => t('preview.fontDefault'));
+
+  useEffect(() => {
+    let alive = true;
+    const name = `deckbuilder-preview-${++counter}`;
+    const face = new FontFace(name, data.slice().buffer);
+    setFamily(undefined);
+    setFailed(false);
+    face.load().then(
+      (loaded) => {
+        if (!alive) return;
+        document.fonts.add(loaded);
+        setFamily(name);
+      },
+      () => alive && setFailed(true),
+    );
+    return () => {
+      alive = false;
+      document.fonts.delete(face);
+    };
+  }, [data]);
+
+  if (failed) return <PanelBanner tone="err" icon="alert">{t('preview.fontError')}</PanelBanner>;
+  if (!family) return null;
+  return (
+    <div className="file-preview">
+      <div className="file-preview-bar archive-bar">
+        <input className="input font-sample-input" value={sample} onChange={(e) => setSample(e.target.value)} placeholder={t('preview.fontSample')} aria-label={t('preview.fontSample')} />
+      </div>
+      <div className="file-preview-body font-view" style={{ fontFamily: `"${family}", sans-serif` }}>
+        <pre className="font-alphabet">{ALPHABET}</pre>
+        {SIZES.map((px) => <div key={px} className="font-line" style={{ fontSize: px }}><span className="font-size">{px}</span>{sample}</div>)}
+      </div>
+    </div>
+  );
+}

package/src/HarView.tsx

@@ -0,0 +1,70 @@
+import { formatBytes, PanelBanner, t } from '@deckbuilderkit/ui';
+import { useMemo, useState } from 'react';
+import { DataGrid } from './TableView';
+import { compareCells } from './table';
+
+interface HarEntry {
+  startedDateTime?: string;
+  time?: number;
+  request?: { method?: string; url?: string };
+  response?: { status?: number; content?: { size?: number; mimeType?: string }; bodySize?: number };
+}
+
+/** A browser HAR capture as a request table with filter and sort. */
+export function HarView({ text }: { text: string }) {
+  const parsed = useMemo(() => {
+    try {
+      const entries = (JSON.parse(text) as { log?: { entries?: HarEntry[] } }).log?.entries;
+      if (!Array.isArray(entries)) return { error: 'log.entries' };
+      const rows = entries.map((e) => {
+        const size = e.response?.content?.size ?? e.response?.bodySize ?? 0;
+        return [
+          e.request?.method ?? '',
+          e.request?.url ?? '',
+          String(e.response?.status ?? ''),
+          (e.response?.content?.mimeType ?? '').split(';')[0]!,
+          String(Math.max(0, size)),
+          String(Math.round(e.time ?? 0)),
+        ];
+      });
+      return { rows, bytes: rows.reduce((sum, r) => sum + Number(r[4]), 0) };
+    } catch (err) {
+      return { error: (err as Error).message };
+    }
+  }, [text]);
+  const [filter, setFilter] = useState('');
+  const [sort, setSort] = useState<{ column: number; desc: boolean } | null>(null);
+
+  const rows = useMemo(() => {
+    if ('error' in parsed) return [];
+    const q = filter.trim().toLowerCase();
+    let out = q ? parsed.rows.filter((r) => r.some((c) => c.toLowerCase().includes(q))) : parsed.rows;
+    if (sort) {
+      const sign = sort.desc ? -1 : 1;
+      out = [...out].sort((a, b) => sign * compareCells(a[sort.column]!, b[sort.column]!));
+    }
+    return out;
+  }, [parsed, filter, sort]);
+
+  if ('error' in parsed) return <PanelBanner tone="err">{t('preview.harInvalid', { message: parsed.error ?? '' })}</PanelBanner>;
+
+  const shown = rows.slice(0, 2000).map((r) => [r[0]!, r[1]!, r[2]!, r[3]!, formatBytes(Number(r[4])), `${r[5]} ms`]);
+  const onSort = (column: number) =>
+    setSort((s) => (s?.column !== column ? { column, desc: false } : s.desc ? null : { column, desc: true }));
+  return (
+    <div className="file-preview">
+      <div className="file-preview-bar archive-bar">
+        <span className="archive-summary">{t('preview.harSummary', { count: parsed.rows.length, size: formatBytes(parsed.bytes) })}</span>
+        <input className="input archive-filter" value={filter} onChange={(e) => setFilter(e.target.value)} placeholder={t('preview.filter')} aria-label={t('preview.filter')} />
+      </div>
+      <div className="file-preview-body">
+        <DataGrid
+          columns={[t('preview.col.method'), t('preview.col.url'), t('preview.col.status'), t('preview.col.type'), t('preview.col.size'), t('preview.col.time')]}
+          rows={shown}
+          sort={sort}
+          onSort={onSort}
+        />
+      </div>
+    </div>
+  );
+}

package/src/HexView.tsx

@@ -0,0 +1,28 @@
+import { formatBytes, PanelBanner, t } from '@deckbuilderkit/ui';
+import { useMemo } from 'react';
+import { hexRows } from './table';
+
+/** Bytes the hex view asks for; a longer file shows only its start. */
+export const HEX_LIMIT = 64 * 1024;
+
+/** A hex dump: offset, 16 bytes in hex and their printable characters. */
+export function HexView({ bytes }: { bytes: Uint8Array }) {
+  const rows = useMemo(() => hexRows(bytes), [bytes]);
+  return (
+    <div className="file-preview">
+      {bytes.length >= HEX_LIMIT && <PanelBanner tone="warn" icon="alert">{t('preview.hexCapped', { size: formatBytes(HEX_LIMIT) })}</PanelBanner>}
+      <div className="file-preview-bar archive-bar"><span className="archive-summary">{formatBytes(bytes.length)}</span></div>
+      <div className="file-preview-body">
+        <pre className="hex-view">
+          {rows.map((r) => (
+            <div key={r.offset} className="hex-row">
+              <span className="hex-offset">{r.offset}</span>
+              <span className="hex-bytes">{r.hex}</span>
+              <span className="hex-ascii">{r.ascii}</span>
+            </div>
+          ))}
+        </pre>
+      </div>
+    </div>
+  );
+}

package/src/HtmlPreview.tsx

@@ -0,0 +1,23 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * An HTML file in a sandboxed frame. With `viewHtml` the frame loads the page from the server, so its scripts
+ * run (the app's CSP blocks them in `srcDoc`) and its relative files resolve; the frame has no same-origin access to the app.
+ */
+export function HtmlPreview({ name, text, viewHtml }: { name: string; text: string; viewHtml?(): Promise<string> }) {
+  const [url, setUrl] = useState<string>();
+
+  useEffect(() => {
+    setUrl(undefined);
+    if (!viewHtml) return;
+    let live = true;
+    viewHtml().then((u) => live && setUrl(u), () => {});
+    return () => {
+      live = false;
+    };
+  }, [viewHtml, text]);
+
+  return url
+    ? <iframe className="file-preview-html" title={name} sandbox="allow-scripts" src={url} />
+    : <iframe className="file-preview-html" title={name} sandbox="" srcDoc={viewHtml ? '' : text} />;
+}

package/src/MarkdownEditor.tsx

@@ -0,0 +1,90 @@
+import { SplitView } from '@deckbuilderkit/ui';
+import { useDeferredValue, useEffect, useMemo, useRef, useState } from 'react';
+import { CodeEditor, type SelectionInfo } from './CodeEditor';
+import { markdownLive } from './markdownLive';
+import { MarkdownView } from './MarkdownView';
+
+export type MarkdownMode = 'live' | 'edit' | 'split' | 'preview';
+
+export const MARKDOWN_MODES: readonly MarkdownMode[] = ['live', 'edit', 'split', 'preview'];
+
+/** Where the text column sits in the Live and Preview views; `full` fits it to the width. */
+export type MarkdownLayout = 'left' | 'center' | 'full';
+
+export const MARKDOWN_LAYOUTS: readonly MarkdownLayout[] = ['left', 'center', 'full'];
+
+const LAYOUT_KEY = 'deckbuilder.markdownLayout';
+
+function readLayout(): MarkdownLayout {
+  try {
+    const v = localStorage.getItem(LAYOUT_KEY);
+    return MARKDOWN_LAYOUTS.find((l) => l === v) ?? 'center';
+  } catch {
+    return 'center';
+  }
+}
+
+const layoutListeners = new Set<(l: MarkdownLayout) => void>();
+
+/** The markdown text column layout, kept in localStorage and shared by every editor of the page. */
+export function useMarkdownLayout(): [MarkdownLayout, (l: MarkdownLayout) => void] {
+  const [layout, setState] = useState<MarkdownLayout>(readLayout);
+  useEffect(() => {
+    layoutListeners.add(setState);
+    return () => void layoutListeners.delete(setState);
+  }, []);
+  const set = (l: MarkdownLayout) => {
+    try { localStorage.setItem(LAYOUT_KEY, l); } catch { /* storage unavailable */ }
+    for (const fn of layoutListeners) fn(l);
+  };
+  return [layout, set];
+}
+
+export interface MarkdownEditorProps {
+  value: string;
+  onChange(value: string): void;
+  /** The view; the host shows the switch (and the layout choice) itself. */
+  mode: MarkdownMode;
+  layout?: MarkdownLayout;
+  resolveImage?(src: string): string | null;
+  autoFocus?: boolean;
+  /** Wrap long lines in the editor; default on. */
+  wrap?: boolean;
+  onSelection?(info: SelectionInfo): void;
+  /** Show the heading rail in the Preview view; default on. */
+  toc?: boolean;
+}
+
+/** A markdown editor in one of four views: Live (rendered while editing), Source, Split (source and preview) or Preview. */
+export function MarkdownEditor({ value, onChange, mode, layout = 'center', resolveImage, autoFocus, wrap = true, onSelection, toc = true }: MarkdownEditorProps) {
+  const deferred = useDeferredValue(value);
+  const preview = useRef<HTMLDivElement>(null);
+  const liveExt = useMemo(() => markdownLive(resolveImage), [resolveImage]);
+  const [sizes, setSizes] = useState([0.5, 0.5]);
+
+  // Proportional: the preview sits at the same fraction of its range as the editor.
+  const syncScroll = (fraction: number) => {
+    const el = preview.current;
+    if (el) el.scrollTop = fraction * (el.scrollHeight - el.clientHeight);
+  };
+
+  const editor = (
+    <CodeEditor key="editor" value={value} lang="markdown" onChange={onChange} height="100%" autoFocus={autoFocus} wrap={wrap}
+      onScroll={mode === 'split' ? syncScroll : undefined} extensions={mode === 'live' ? liveExt : undefined} onSelection={onSelection} />
+  );
+  const rendered = (
+    <div key="preview" ref={preview} className="md-editor-preview">
+      <MarkdownView markdown={deferred} resolveImage={resolveImage} toc={toc && mode === 'preview'} />
+    </div>
+  );
+
+  return (
+    <div className="md-editor" data-layout={layout} data-mode={mode}>
+      <div className="md-editor-body">
+        {mode === 'edit' || mode === 'live' ? editor
+          : mode === 'preview' ? rendered
+            : <SplitView direction="row" sizes={sizes} defaultSizes={[0.5, 0.5]} min={[200, 200]} onResize={setSizes}>{editor}{rendered}</SplitView>}
+      </div>
+    </div>
+  );
+}

package/src/MarkdownToc.tsx

@@ -0,0 +1,135 @@
+import { rovingIndex, t } from '@deckbuilderkit/ui';
+import { type KeyboardEvent, type RefObject, useEffect, useRef, useState } from 'react';
+import { activeHeading } from './toc';
+
+/** A rendered h1–h3, kept by reference: the sanitizer strips ids, so there is nothing to link to. */
+export interface TocHeading {
+  el: HTMLElement;
+  level: number;
+  text: string;
+}
+
+/** Tick width per heading level (h1, h2, h3). */
+const TICK = [20, 14, 8];
+/** Vertical distance between ticks; matches `.md-toc-tick` height plus margin. */
+const GAP = 8;
+/** A heading this close below the container's top already counts as the one being read. */
+const SPY_OFFSET = 16;
+/** Where a jumped-to heading lands below the container's top. */
+const JUMP_OFFSET = 8;
+
+/** The nearest ancestor that scrolls vertically. */
+function scrollParent(el: HTMLElement | null): HTMLElement | null {
+  for (let p = el?.parentElement; p; p = p.parentElement) {
+    const { overflowY } = getComputedStyle(p);
+    if (overflowY === 'auto' || overflowY === 'scroll') return p;
+  }
+  return null;
+}
+
+/** A rail of heading ticks pinned to the left of the rendered markdown, with scroll-spy; a click lists the headings. */
+export function MarkdownToc({ headings, content }: { headings: TocHeading[]; content: RefObject<HTMLElement | null> }) {
+  const root = useRef<HTMLDivElement>(null);
+  const rail = useRef<HTMLButtonElement>(null);
+  const panel = useRef<HTMLElement>(null);
+  const [active, setActive] = useState(0);
+  const [open, setOpen] = useState(false);
+  const shown = headings.length >= 2;
+
+  useEffect(() => {
+    const box = scrollParent(root.current);
+    if (!box || !shown) return;
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      const top = box.getBoundingClientRect().top;
+      const tops = headings.map((h) => h.el.getBoundingClientRect().top - top);
+      const atBottom = box.scrollHeight > box.clientHeight && box.scrollTop + box.clientHeight >= box.scrollHeight - 1;
+      setActive(Math.max(0, activeHeading(tops, SPY_OFFSET, atBottom)));
+    };
+    const schedule = () => {
+      if (!frame) frame = requestAnimationFrame(update);
+    };
+    update();
+    box.addEventListener('scroll', schedule, { passive: true });
+    const resize = new ResizeObserver(schedule);
+    resize.observe(box);
+    if (content.current) resize.observe(content.current);
+    return () => {
+      box.removeEventListener('scroll', schedule);
+      resize.disconnect();
+      cancelAnimationFrame(frame);
+    };
+  }, [headings, content, shown]);
+
+  useEffect(() => {
+    if (!open) return;
+    const list = panel.current;
+    const item = list?.querySelector<HTMLButtonElement>('.md-toc-item.active');
+    if (list && item) {
+      list.scrollTop = item.offsetTop - (list.clientHeight - item.offsetHeight) / 2;
+      item.focus({ preventScroll: true });
+    }
+    const onDown = (e: PointerEvent) => {
+      if (!root.current?.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('pointerdown', onDown);
+    return () => document.removeEventListener('pointerdown', onDown);
+  }, [open]);
+
+  if (!shown) return null;
+
+  const close = () => {
+    setOpen(false);
+    rail.current?.focus({ preventScroll: true });
+  };
+
+  const jump = (h: TocHeading) => {
+    close();
+    const box = scrollParent(root.current);
+    if (!box) return;
+    const top = box.scrollTop + h.el.getBoundingClientRect().top - box.getBoundingClientRect().top - JUMP_OFFSET;
+    box.scrollTo({ top, behavior: 'smooth' });
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (!open) return;
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      close();
+      return;
+    }
+    const items = [...(panel.current?.querySelectorAll<HTMLButtonElement>('.md-toc-item') ?? [])];
+    const next = rovingIndex(e.key, items.indexOf(document.activeElement as HTMLButtonElement), items.length, 10);
+    if (next === null) return;
+    e.preventDefault();
+    items[next]?.focus();
+  };
+
+  return (
+    <div ref={root} className="md-toc" onKeyDown={onKeyDown}>
+      <button ref={rail} type="button" className="md-toc-rail" aria-expanded={open} aria-label={t('preview.toc')} title={t('preview.toc')}
+        onClick={() => setOpen(!open)}>
+        {headings.map((h, i) => (
+          <span key={i} className={'md-toc-tick' + (i === active ? ' active' : '')} style={{ width: TICK[h.level - 1] }} />
+        ))}
+        <span className="md-toc-indicator" style={{ transform: `translateY(${active * GAP}px)` }} />
+      </button>
+      {open && (
+        <nav ref={panel} className="md-toc-panel" aria-label={t('preview.toc')}>
+          <ul>
+            {headings.map((h, i) => (
+              <li key={i}>
+                <button type="button" className={'md-toc-item' + (i === active ? ' active' : '')} aria-current={i === active ? 'location' : undefined}
+                  style={{ paddingLeft: 10 + (h.level - 1) * 12 }} onClick={() => jump(h)}>
+                  {h.text}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      )}
+    </div>
+  );
+}

package/src/MarkdownView.tsx

@@ -0,0 +1,84 @@
+import { copyText, t } from '@deckbuilderkit/ui';
+import { classHighlighter, highlightTree } from '@lezer/highlight';
+import { type MouseEvent, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { langOfFile, type Parser, parserOf } from './languages';
+import { renderMarkdown } from './markdown';
+import { MarkdownToc, type TocHeading } from './MarkdownToc';
+
+/** Replaces a code element's text with `tok-*` spans (classHighlighter); styled by `.markdown .tok-*`. */
+function highlightCode(code: HTMLElement, parser: Parser) {
+  const text = code.textContent ?? '';
+  const out = document.createDocumentFragment();
+  let pos = 0;
+  highlightTree(parser.parse(text), classHighlighter, (from, to, classes) => {
+    if (from > pos) out.append(text.slice(pos, from));
+    const span = document.createElement('span');
+    span.className = classes;
+    span.textContent = text.slice(from, to);
+    out.append(span);
+    pos = to;
+  });
+  if (pos < text.length) out.append(text.slice(pos));
+  code.replaceChildren(out);
+}
+
+/**
+ * Rendered, sanitized markdown; code blocks highlighted when their fence names a file extension with a parser.
+ * `toc` adds a heading rail (MarkdownToc) that tracks the nearest scrolling ancestor.
+ */
+export function MarkdownView({ markdown, resolveImage, toc }: { markdown: string; resolveImage?(src: string): string | null; toc?: boolean }) {
+  const host = useRef<HTMLDivElement>(null);
+  const [headings, setHeadings] = useState<TocHeading[]>([]);
+  const html = useMemo(
+    () => renderMarkdown(markdown, { resolveImage, blockedLabel: t('preview.remoteImageBlocked') }),
+    [markdown, resolveImage],
+  );
+
+  useLayoutEffect(() => {
+    for (const code of host.current?.querySelectorAll<HTMLElement>('pre > code[class*="language-"]') ?? []) {
+      const fence = /language-(\w+)/.exec(code.className)?.[1];
+      const parser = fence ? parserOf(fence.toLowerCase() === 'shell' ? 'shell' : langOfFile('x.' + fence)) : null;
+      if (parser) highlightCode(code, parser);
+    }
+    for (const pre of host.current?.querySelectorAll<HTMLElement>('pre') ?? []) {
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'md-code-copy';
+      button.textContent = t('output.copyAll');
+      const wrap = document.createElement('div');
+      wrap.className = 'md-code';
+      pre.replaceWith(wrap);
+      wrap.append(pre, button);
+    }
+  }, [html]);
+
+  useLayoutEffect(() => {
+    if (!toc) return;
+    setHeadings([...(host.current?.querySelectorAll<HTMLElement>('h1, h2, h3') ?? [])]
+      .map((el) => ({ el, level: Number(el.tagName[1]), text: el.textContent?.trim() ?? '' })));
+  }, [html, toc]);
+
+  const onClick = async (e: MouseEvent<HTMLDivElement>) => {
+    const button = e.target as HTMLElement;
+    if (button.closest('a[href^="#"]')) {
+      e.preventDefault();
+      return;
+    }
+    if (!button.classList.contains('md-code-copy')) return;
+    const code = button.parentElement?.querySelector('code') ?? button.parentElement;
+    if (!code || !(await copyText(code.textContent ?? ''))) return;
+    button.textContent = t('common.copied');
+    setTimeout(() => {
+      button.textContent = t('output.copyAll');
+    }, 1500);
+  };
+
+  const view = <div ref={host} className="markdown" onClick={onClick} dangerouslySetInnerHTML={{ __html: html }} />;
+  if (!toc) return view;
+  return (
+    <div className={'md-toc-wrap' + (headings.length >= 2 ? ' has-toc' : '')}>
+      <MarkdownToc headings={headings} content={host} />
+      {view}
+    </div>
+  );
+}

package/src/MediaView.tsx

@@ -0,0 +1,17 @@
+import { PanelBanner, t } from '@deckbuilderkit/ui';
+import { useState } from 'react';
+
+/** An audio or video file played from a blob URL. */
+export function MediaView({ url, video }: { url: string; video: boolean }) {
+  const [failed, setFailed] = useState(false);
+  return (
+    <div className="file-preview">
+      {failed && <PanelBanner tone="err" icon="alert">{t('preview.mediaError')}</PanelBanner>}
+      <div className="file-preview-body file-preview-image">
+        {video
+          ? <video className="media-video" src={url} controls onError={() => setFailed(true)} />
+          : <audio className="media-audio" src={url} controls onError={() => setFailed(true)} />}
+      </div>
+    </div>
+  );
+}