@lincyaw/viewer 1.0.0-rc.13 → 1.0.0-rc.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/viewer",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.14",
   "description": "Presmium's IR runtime: renders the IR in the browser, with runtime views and live updates",
   "license": "Apache-2.0",
   "repository": {
@@ -56,8 +56,8 @@
     "react-dom": "18.3.1",
     "shiki": "4.5.0",
     "style-to-js": "2.0.2",
-    "@lincyaw/host": "1.0.0-rc.13",
-    "@lincyaw/kernel": "1.0.0-rc.13"
+    "@lincyaw/host": "1.0.0-rc.14",
+    "@lincyaw/kernel": "1.0.0-rc.14"
   },
   "devDependencies": {
     "@types/hast": "3.0.5",

package/src/client/block.ts

@@ -6,6 +6,7 @@ import type { ComponentNode, IRBlock, IRSection } from '@lincyaw/kernel'
 import { FINAL_STEP } from '../domain/index.ts'
 import { CODE_OWNED, CodeBlockView } from './code/code-block.ts'
 import { contentMarks } from './content-marks.ts'
+import { loadedParts } from './deferred.ts'
 import { markdownToHast } from './markdown/handlers.ts'
 import { PmMermaid } from './markdown/mermaid.ts'
 import { hastToVNodes, MarkdownView } from './markdown/render.ts'
@@ -18,7 +19,7 @@ import { SECTION_CONTEXT } from './section-context.ts'
 export interface BlockProps { block: IRBlock, section: IRSection, step: number, expanded?: boolean, localPreview?: boolean }
 const COMPONENT_NODE = createContext<{ node: ComponentNode, section: string } | undefined>(undefined)
 function fallbackOf(node: ComponentNode, section: string) { return node.fallback ? hastToVNodes(markdownToHast(node.fallback, section).children, {}) : [] }
-export function PmComponentFallback() { const current = useContext(COMPONENT_NODE); return current ? h('div', { className: 'pm-component-fallback' }, fallbackOf(current.node, current.section)) : null }
+export function PmComponentFallback() { const current = useContext(COMPONENT_NODE); useStore(loadedParts); return current ? h('div', { className: 'pm-component-fallback' }, fallbackOf(current.node, current.section)) : null }
 function ComponentView(props: BlockProps) {
   const node = props.block.node as ComponentNode
   const printed = useStaticRender()
@@ -44,6 +45,8 @@ function content(props: BlockProps): ReactNode {
 function BlockViewContent(props: BlockProps) {
   const viewer = useContext(VIEWER); const el = useRef<HTMLDivElement>(null)
   useStore(registryRevision)
+  // A part of the viewer the block needed and did not have yet (`deferred.ts`) has arrived.
+  useStore(loadedParts)
   useEffect(() => el.current ? trackClicks(el.current, props.expanded ? FINAL_STEP : props.step) : undefined, [props.step, props.expanded, props.block])
   const { block } = props
   const visible = props.expanded || blockVisible(block, props.step)

package/src/client/code/code-view.ts

@@ -1,9 +1,9 @@
 import { useAppearance, usePrefersReducedMotion } from '@lincyaw/host'
-import { ShikiMagicMove } from '@shikijs/magic-move/react'
 import '@shikijs/magic-move/style.css'
 import { useEffect, useState } from 'react'
+import type { ComponentProps, ComponentType } from 'react'
+import type { ShikiMagicMove } from '@shikijs/magic-move/react'
 import type { Element, ElementContent, Root } from 'hast'
-import { toHtml } from 'hast-util-to-html'
 import { codeColumns } from '../../domain/index.ts'
 import { highlighterFor, SHIKI_THEMES } from './highlight.ts'
 import { h } from '../element.ts'
@@ -13,10 +13,14 @@ function lineElements(tree: Root): Element[] { const pre = tree.children.find((n
 export function CodeView({ lang = '', value, highlight }: { lang?: string, value: string, highlight?: number[] }) {
   const shiki = useHighlighter(lang); const code = value.replace(/\n$/, ''); const lines = new Set(highlight ?? [])
   let html: string | undefined
-  if (shiki) { const tree = shiki.highlighter.codeToHast(code, { lang: shiki.lang, themes: SHIKI_THEMES, defaultColor: false }); lineElements(tree).forEach((line, i) => line.properties.class = lines.has(i + 1) ? 'line highlighted' : 'line'); html = toHtml(tree) }
+  if (shiki) { const tree = shiki.highlighter.codeToHast(code, { lang: shiki.lang, themes: SHIKI_THEMES, defaultColor: false }); lineElements(tree).forEach((line, i) => line.properties.class = lines.has(i + 1) ? 'line highlighted' : 'line'); html = shiki.toHtml(tree) }
   const attrs = { className: `pm-code${lines.size ? ' pm-code--highlight' : ''}`, style: { '--pm-code-columns': codeColumns(code) }, 'data-lang': lang || undefined }
   if (html) return h('div', { ...attrs, innerHTML: html })
   const rows = code.split('\n').flatMap((text, i) => [h('span', { key: i, className: `line${lines.has(i + 1) ? ' highlighted' : ''}` }, text), '\n'])
   return h('div', attrs, h('pre', { className: 'shiki' }, h('code', {}, rows.slice(0, -1))))
 }
-export function VariantView({ lang = '', value }: { lang?: string, value: string }) { const loaded = useHighlighter(lang); const reduced = usePrefersReducedMotion(); const { dark } = useAppearance(); if (!loaded || reduced) return h(CodeView, { lang, value }); const code = value.replace(/\n$/, ''); return h('div', { className: 'pm-code pm-code--magic-move', style: { '--pm-code-columns': codeColumns(code) }, 'data-lang': lang || undefined }, h(ShikiMagicMove, { highlighter: loaded.highlighter, lang: loaded.lang, theme: dark ? SHIKI_THEMES.dark : SHIKI_THEMES.light, code })) }
+type MagicMove = ComponentType<ComponentProps<typeof ShikiMagicMove>>
+let magicMove: Promise<MagicMove> | undefined
+/** The animation between variants, loaded once a page shows one (until then, and on the server, the listing alone). */
+function useMagicMove(wanted: boolean) { const [move, setMove] = useState<MagicMove>(); useEffect(() => { if (!wanted || move) return; let active = true; magicMove ??= import('@shikijs/magic-move/react').then(m => m.ShikiMagicMove as MagicMove); void magicMove.then(value => { if (active) setMove(() => value) }).catch(() => {}); return () => { active = false } }, [wanted]); return move }
+export function VariantView({ lang = '', value }: { lang?: string, value: string }) { const loaded = useHighlighter(lang); const reduced = usePrefersReducedMotion(); const { dark } = useAppearance(); const ShikiMagicMove = useMagicMove(!reduced); if (!loaded || reduced || !ShikiMagicMove) return h(CodeView, { lang, value }); const code = value.replace(/\n$/, ''); return h('div', { className: 'pm-code pm-code--magic-move', style: { '--pm-code-columns': codeColumns(code) }, 'data-lang': lang || undefined }, h(ShikiMagicMove, { highlighter: loaded.highlighter, lang: loaded.lang, theme: dark ? SHIKI_THEMES.dark : SHIKI_THEMES.light, code })) }

package/src/client/code/highlight.ts

@@ -1,5 +1,6 @@
 import { languageId } from '@lincyaw/kernel'
 import type { HighlighterCore } from 'shiki/core'
+import type { toHtml } from 'hast-util-to-html'
 
 type Loader = () => Promise<unknown>
 
@@ -43,17 +44,22 @@ const ALIASES: Record<string, string> = {
 
 export const SHIKI_THEMES = { light: 'github-light', dark: 'github-dark' } as const
 
-let highlighter: Promise<HighlighterCore> | undefined
+/** Shiki, with what writes its trees as HTML. */
+interface Loaded { highlighter: HighlighterCore, toHtml: typeof toHtml }
+
+let highlighter: Promise<Loaded> | undefined
 const loading = new Map<string, Promise<void>>()
 
-function load(): Promise<HighlighterCore> {
+function load(): Promise<Loaded> {
   if (import.meta.env.SSR) return new Promise(() => {})
-  highlighter ??= Promise.all([import('shiki/core'), import('shiki/engine/javascript')]).then(([core, engine]) =>
-    core.createHighlighterCore({
+  highlighter ??= Promise.all([import('shiki/core'), import('shiki/engine/javascript'), import('hast-util-to-html')]).then(async ([core, engine, html]) => ({
+    highlighter: await core.createHighlighterCore({
       themes: [import('shiki/themes/github-light.mjs'), import('shiki/themes/github-dark.mjs')],
       langs: [],
       engine: engine.createJavaScriptRegexEngine({ forgiving: true }),
-    }))
+    }),
+    toHtml: html.toHtml,
+  }))
   return highlighter
 }
 
@@ -63,11 +69,11 @@ function grammarOf(lang: string): string | undefined {
   return name in GRAMMARS ? name : undefined
 }
 
-export async function highlighterFor(lang: string): Promise<{ highlighter: HighlighterCore, lang: string } | undefined> {
+export async function highlighterFor(lang: string): Promise<Loaded & { lang: string } | undefined> {
   const name = grammarOf(lang)
   if (!name) return undefined
-  const core = await load()
-  if (!loading.has(name)) loading.set(name, core.loadLanguage(GRAMMARS[name]!() as never))
+  const loaded = await load()
+  if (!loading.has(name)) loading.set(name, loaded.highlighter.loadLanguage(GRAMMARS[name]!() as never))
   await loading.get(name)
-  return { highlighter: core, lang: name }
+  return { ...loaded, lang: name }
 }

package/src/client/code/output-parsers.ts

@@ -0,0 +1,19 @@
+import { htmlAsText } from '@lincyaw/kernel'
+import type { MdastNode } 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'
+
+/** What the outputs of code runs are read with, loaded once a page shows one (`deferred.ts`). */
+export interface OutputParsers {
+  /** Terminal text with its ANSI colours, as HTML. */
+  ansi(text: string): string
+  /** A Markdown output as MDAST, its raw HTML as text. */
+  markdown(text: string): MdastNode
+}
+
+export const OUTPUT_PARSERS: OutputParsers = {
+  ansi: text => new AnsiUp().ansi_to_html(text),
+  markdown: text => htmlAsText(fromMarkdown(text, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] }) as unknown as MdastNode),
+}

package/src/client/code/outputs.ts

@@ -1,14 +1,11 @@
 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 { escapeHtml, isProseRun } from '@lincyaw/kernel'
+import type { RunOutput, RunResult } from '@lincyaw/kernel'
 import type { ReactElement, ReactNode } from 'react'
 import { useEffect, useState } from 'react'
 import { h } from '../element.ts'
 import { outputNotes } from '../../domain/index.ts'
+import { codeOutputParsers } from '../deferred.ts'
 import { markdownToHast } from '../markdown/handlers.ts'
 import { PmMath } from '../markdown/math.ts'
 import { hastToVNodes } from '../markdown/render.ts'
@@ -20,13 +17,14 @@ function text(value: unknown): string {
   return Array.isArray(value) ? value.join('') : typeof value === 'string' ? value : JSON.stringify(value, null, 2)
 }
 
+// Until the parsers are loaded (`deferred.ts`), terminal text shows without its colours and Markdown as written.
 function ansi(value: string): string {
-  return new AnsiUp().ansi_to_html(value)
+  return codeOutputParsers()?.ansi(value) ?? escapeHtml(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, {})
+  const parsers = codeOutputParsers()
+  return parsers ? hastToVNodes(markdownToHast(parsers.markdown(markdown), prefix).children, {}) : [h('pre', { key: 0, className: 'pm-output__text' }, markdown)]
 }
 
 let purify: Promise<(html: string) => string> | undefined

package/src/client/deferred.ts

@@ -0,0 +1,65 @@
+import { createStore } from '@lincyaw/host'
+import { docBlocks } from '@lincyaw/kernel'
+import type { IRDocument, MdastNode } from '@lincyaw/kernel'
+import type { raw } from 'hast-util-raw'
+import type { OutputParsers } from './code/output-parsers.ts'
+
+/**
+ * The parts of the viewer that only some documents use, loaded apart from the app: the HTML parser for HTML written in
+ * Markdown, and the parsers of code outputs (ANSI colours, Markdown). A page loads the parts its document uses before it
+ * first renders (`loadDocumentParts`), so that the server's render and the browser's first one agree; a part a later
+ * change of the document needs loads then, and the blocks render again once it is there.
+ */
+
+type RawHtml = typeof raw
+
+/** Counts the parts loaded, so that a block shown without one renders again once it is there. */
+export const loadedParts = createStore(0)
+let rawHtml: RawHtml | undefined
+let outputParsers: OutputParsers | undefined
+const loading = new Map<string, Promise<void>>()
+
+function load(name: string, start: () => Promise<void>): Promise<void> {
+  let known = loading.get(name)
+  if (!known) {
+    known = start().then(
+      () => loadedParts.set(loadedParts.getSnapshot() + 1),
+      (error: unknown) => {
+        loading.delete(name)
+        console.error(`[presmium] the viewer's ${name} did not load`, error)
+      },
+    )
+    loading.set(name, known)
+  }
+  return known
+}
+
+const loadRawHtml = () => load('HTML parser', async () => { rawHtml = (await import('hast-util-raw')).raw })
+const loadOutputParsers = () => load('output parsers', async () => { outputParsers = (await import('./code/output-parsers.ts')).OUTPUT_PARSERS })
+
+/** The HTML parser if it is loaded; else it starts loading and the caller shows the HTML as missing meanwhile. */
+export function rawHtmlParser(): RawHtml | undefined {
+  if (!rawHtml) void loadRawHtml()
+  return rawHtml
+}
+
+/** The parsers of code outputs if they are loaded; else they start loading and the caller shows plain text meanwhile. */
+export function codeOutputParsers(): OutputParsers | undefined {
+  if (!outputParsers) void loadOutputParsers()
+  return outputParsers
+}
+
+function hasHtml(node: MdastNode | undefined): boolean {
+  return node !== undefined && (node.type === 'html' || (node.children?.some(hasHtml) ?? false))
+}
+
+/** Loads the parts `doc` uses (`import.meta.env.SSR` included: the server renders the document with them too). */
+export async function loadDocumentParts(doc: IRDocument): Promise<void> {
+  const parts: Promise<void>[] = []
+  for (const { block } of docBlocks(doc)) {
+    const node = block.node
+    if (!rawHtml && ((node.type === 'markdown' && hasHtml(node.mdast)) || (node.type === 'component' && hasHtml(node.fallback)))) parts.push(loadRawHtml())
+    if (!outputParsers && node.type === 'code' && node.outputs?.length) parts.push(loadOutputParsers())
+  }
+  await Promise.all(parts)
+}

package/src/client/index.ts

@@ -22,6 +22,7 @@ Object.entries(DOCUMENT_LAYOUT_COMPONENTS).forEach(([name, component]) => regist
 export function ViewerProvider({ viewer, children }: { viewer: Viewer, children?: ReactNode }) { return createElement(VIEWER.Provider, { value: viewer }, children) }
 
 export { BlockView, BlockPreview, PmComponentFallback } from './block.ts'
+export { loadDocumentParts } from './deferred.ts'
 export { syncViewerWithOperations } from './operations.ts'
 export { findView, findComponent, listViews, registerComponent, registryRevision } from './registry.ts'
 export type { NodeRenderer, ViewDefinition, ViewerAction, ViewerLayer } from './registry.ts'

package/src/client/markdown/handlers.ts

@@ -1,9 +1,9 @@
 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 { rawHtmlParser } from '../deferred.ts'
 import { viewerMessages } from '../viewer-messages.ts'
 import { footnoteId } from '../viewer-state.ts'
 import type { Viewer } from '../viewer-state.ts'
@@ -145,9 +145,35 @@ function textOf(node: ElementContent | Root): string {
   return 'children' in node ? node.children.map(c => textOf(c as ElementContent)).join('') : ''
 }
 
+function hasRaw(node: Nodes): boolean {
+  return node.type === 'raw' || ('children' in node && node.children.some(child => hasRaw(child as Nodes)))
+}
+
+/** Joins the neighbouring texts of a tree, as parsing it as HTML does (`hast-util-raw`), so that it renders as one text. */
+function joinTexts(node: Nodes): void {
+  if (!('children' in node)) return
+  const children: Nodes[] = []
+  for (const child of node.children as Nodes[]) {
+    const last = children.at(-1)
+    if (child.type === 'text' && last?.type === 'text') last.value += child.value
+    else children.push(child)
+    joinTexts(child)
+  }
+  node.children = children as never
+}
+
+/** The trees made while the HTML parser was loading, without their HTML; they are made again once it is there. */
+const partial = new WeakSet<Root>()
+export const isPartialTree = (tree: Root): boolean => partial.has(tree)
+
 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
+  // HTML written in the Markdown is parsed with the rest (`hast-util-raw`); without any, the tree needs no HTML parser.
+  const written = hasRaw(html)
+  const raw = written ? rawHtmlParser() : undefined
+  if (!raw) joinTexts(html)
+  const tree = (raw ? raw(html, { passThrough: VIEWER_NODES }) : html) as Root
+  if (written && !raw) partial.add(tree)
   let item = 0
   for (const child of tree.children) {
     if (child.type !== 'element') continue

package/src/client/markdown/tree-cache.ts

@@ -2,7 +2,7 @@ import type { IRDocument, MdastNode } from '@lincyaw/kernel'
 import type { Root } from 'hast'
 import type { Viewer } from '../viewer-state.ts'
 import { footnoteSections } from '../../domain/index.ts'
-import { markdownToHast } from './handlers.ts'
+import { isPartialTree, markdownToHast } from './handlers.ts'
 import type { MarkdownLinks } from './handlers.ts'
 
 interface CachedTree {
@@ -58,7 +58,7 @@ export function cachedTree(viewer: Viewer, doc: IRDocument, node: MdastNode, pre
   const tree = markdownToHast(node, prefix, links)
   // Only immutable HAST survives component unmounts; no VNodes or mounted resources are retained.
   const bytes = JSON.stringify(tree).length * 2 // UTF-16 JSON size is a soft heap estimate.
-  if (bytes > TREE_BYTES) return tree
+  if (bytes > TREE_BYTES || isPartialTree(tree)) return tree
   const entry: CachedTree = { node, key, tree, bytes }
   const variants = cache.nodes.get(node) ?? new Map<string, CachedTree>()
   variants.set(key, entry)

package/src/client/views/present.ts

@@ -1,5 +1,6 @@
 import { FocusScope } from '@radix-ui/react-focus-scope'
-import { PmApprovals, PmCaption, PmCaptionProvider, PmIcon, TIMED_CAPTIONS, useService, PLAYBACK_CONTROL, presmiumService } from '@lincyaw/host'
+import { PAGE_READINESS, PmApprovals, PmCaption, PmCaptionProvider, PmIcon, TIMED_CAPTIONS, useService, PLAYBACK_CONTROL, presmiumService } from '@lincyaw/host'
+import { notifyEmbedder } from '@lincyaw/kernel'
 import { useEffect, useRef, useState } from 'react'
 import { useStore } from '@lincyaw/host'
 import { h } from '../element.ts'
@@ -39,6 +40,17 @@ export function PresentView() {
     const [fullscreen, setFullscreen] = useState(false)
     const [captions, setCaptions] = useState(true)
     const timedCaptions = useStore(useService(TIMED_CAPTIONS)?.active, false)
+    // The page that embeds the presentation learns when the current slide is drawn: no component still loading,
+    // checked after the slide's components have mounted and taken their holds.
+    const loading = useStore(useService(PAGE_READINESS)?.pending, 0)
+    useEffect(() => {
+      if (loading > 0) {
+        notifyEmbedder({ drawn: false, section: section?.id, step })
+        return
+      }
+      const frame = requestAnimationFrame(() => notifyEmbedder({ drawn: true, section: section?.id, step }))
+      return () => cancelAnimationFrame(frame)
+    }, [loading, section?.id, step])
     const overview = useStore(overviewOpen)
     const doc = useStore(viewer.doc)
     useStore(viewer.options.confirmedRevision)