@changfenhuang/dsh-genui 0.9.1

package/src/client/PlotBlock.tsx

@@ -0,0 +1,431 @@
+/**
+ * PlotBlock: renders one or more math functions as an SVG line chart. The
+ * model supplies expressions (e.g. "sin(x)") which are evaluated by the
+ * SafeMath white-listed evaluator — never eval — and sampled into polylines.
+ * Pure SVG: linear x/y scales computed in place, no chart library.
+ *
+ * v2 interactivity: series may declare `params` (e.g. {a: 2} in "a*sin(x)")
+ * which render as live sliders under the chart — dragging re-samples the
+ * curve in place. The plot itself supports drag-to-pan and wheel-to-zoom.
+ */
+import { memo, useEffect, useRef, useState, type ReactNode } from 'react'
+import { sampleExpr } from './safe-math.ts'
+import css from './PlotBlock.module.css'
+
+export interface PlotSeriesParam {
+  name: string
+  value: number
+  min?: number | undefined
+  max?: number | undefined
+  step?: number | undefined
+  /** v1.5: animate this parameter from its initial value to this target. */
+  animateTo?: number | undefined
+  /** Animation duration in ms (default 4000). */
+  durationMs?: number | undefined
+  /** Loop the animation (default false). */
+  loop?: boolean | undefined
+}
+
+export interface PlotSeries {
+  /** Math expression in x. */
+  expr: string
+  /** Optional label shown in a legend row. */
+  label?: string | undefined
+  /** Stroke color; defaults to the accent token (multi-series auto-assign). */
+  color?: string | undefined
+  /** v2.9 draw shape: line (default), area (fill to baseline), scatter. */
+  kind?: 'line' | 'area' | 'scatter' | undefined
+  /** v2: adjustable parameters, one slider each, live re-render. */
+  params?: PlotSeriesParam[] | undefined
+}
+
+/** Categorical palette for multi-series plots: host static tokens only
+ * (design system v2 — same families as the chart/avatar palettes in
+ * GenuiBlock, no off-theme hexes). CSS custom properties resolve inside
+ * inline `style` on SVG strokes and legend swatches. */
+export const PLOT_COLORS = [
+  'var(--dsw-static-deepseek-400)',
+  'var(--dsw-static-green-400)',
+  'var(--dsw-static-amber-400)',
+  'var(--dsw-static-red-400)',
+  'var(--dsw-static-blue-450)',
+  'var(--dsw-static-deepseek-450)',
+  'var(--dsw-static-neutral-bluish-400)',
+  'var(--dsw-static-deepseek-300)',
+]
+
+/** Series color: explicit wins; multi-series auto-assign from the palette. */
+const seriesColor = (i: number, n: number, c?: string): string | undefined =>
+  c ?? (n > 1 ? PLOT_COLORS[i % PLOT_COLORS.length] : undefined)
+
+export interface PlotBlockProps {
+  /** Functions to draw, in draw order. */
+  series: PlotSeries[]
+  /** Horizontal range, inclusive. */
+  xMin?: number | undefined
+  xMax?: number | undefined
+  /** Vertical bounds; omitted = auto-fit to the sampled data. */
+  yMin?: number | undefined
+  yMax?: number | undefined
+  /** Chart title. */
+  title?: string | undefined
+}
+
+const WIDTH = 480
+const HEIGHT = 220
+const PAD_L = 34
+const PAD_R = 10
+const PAD_T = 14
+const PAD_B = 24
+const SAMPLES = 240
+
+/** Auto-fit y-range from finite samples with a small margin. */
+function fitY(points: ReadonlyArray<readonly [number, number]>): [number, number] {
+  let lo = Infinity
+  let hi = -Infinity
+  for (const [, y] of points) {
+    if (y < lo) lo = y
+    if (y > hi) hi = y
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return [-1, 1]
+  if (lo === hi) { lo -= 1; hi += 1 }
+  const pad = (hi - lo) * 0.08
+  return [lo - pad, hi + pad]
+}
+
+function niceTicks(min: number, max: number, count = 5): number[] {
+  const span = max - min
+  if (!Number.isFinite(span) || span <= 0) return []
+  const step = Math.pow(10, Math.floor(Math.log10(span / count)))
+  const err = span / count / step
+  const mult = err >= 7.5 ? 10 : err >= 3.5 ? 5 : err >= 1.5 ? 2 : 1
+  const size = step * mult
+  const ticks: number[] = []
+  for (let v = Math.ceil(min / size) * size; v <= max + size * 1e-9; v += size) {
+    ticks.push(Math.round(v * 1e9) / 1e9)
+  }
+  return ticks
+}
+
+function formatTick(v: number): string {
+  if (Math.abs(v) >= 1e5 || (Math.abs(v) < 1e-3 && v !== 0)) return v.toExponential(1)
+  return String(Math.round(v * 100) / 100)
+}
+
+/** Polyline with manual points sync: React 18 does not reliably update the
+ * SVG `points` attribute when only the value changes (the element is diffed
+ * but the attribute write is skipped), so this wrapper writes it through a
+ * ref on every render. */
+function Polyline({ points, className, color }: { points: string; className: string | undefined; color?: string | undefined }) {
+  // React 18 does not reliably update the SVG `points` attribute when the
+  // value changes on an existing element (the DOM write is skipped). Keying
+  // the element on a prefix of the points string forces a fresh element per
+  // distinct curve, which sidesteps the update entirely. The prefix must
+  // change whenever the curve changes: include the first and last point.
+  const key = points.length > 40 ? `${points.slice(0, 16)}|${points.slice(-16)}` : points
+  return (
+    <polyline
+      key={key}
+      points={points}
+      className={className}
+      style={color !== undefined ? { stroke: color } : undefined}
+    />
+  )
+}
+
+/** Render one plot: grid, axes, one polyline per series, legend, sliders. */
+export const PlotBlock = memo(function PlotBlock({
+  series, xMin: propXMin = -5, xMax: propXMax = 5, yMin, yMax, title,
+}: PlotBlockProps) {
+  // Pan/zoom view state: x range plus a LOCKED y range. The y range is fit
+  // ONCE from the initial parameters and then fixed, so dragging a parameter
+  // slider changes the curve's SHAPE (amplitude/slope) instead of rescaling
+  // the axis every time — the user sees the function move, not the numbers.
+  const [view, setView] = useState(() => {
+    // Fit y from the default parameter values (the same fallback the render
+    // path uses), so the initial axis already frames the default curve.
+    const defaults: Record<string, number> = {}
+    for (const [si, s] of series.entries()) {
+      for (const p of s.params ?? []) {
+        if (p !== null && p !== undefined) defaults[`${si}:${p.name}`] = p.value
+      }
+    }
+    const probe = series.map((s, si) => {
+      const p: Record<string, number> = {}
+      for (const param of s.params ?? []) {
+        if (param === null || param === undefined) continue
+        p[param.name] = defaults[`${si}:${param.name}`] ?? param.value
+      }
+      return sampleExpr(s.expr, propXMin, propXMax, SAMPLES, p)
+    })
+    const [autoLo, autoHi] = fitY(probe.flatMap(p => p))
+    return {
+      xMin: propXMin,
+      xMax: propXMax,
+      yMin: yMin ?? autoLo,
+      yMax: yMax ?? autoHi,
+    }
+  })
+  const dragRef = useRef<{ startX: number; startY: number; xMin: number; xMax: number } | null>(null)
+
+  // Parameter values keyed by series index + param name; slider drag updates.
+  // Deliberately starts EMPTY: the initializer must never read series props
+  // (a parent re-mount can rebuild them mid-interaction), so every value
+  // falls back to the param's declared default at render time. This makes
+  // remounts during slider drags crash-proof.
+  const [params, setParams] = useState<Record<string, number>>(() => ({}))
+
+  // Animation: pick the first parameter that declares animateTo. A play/pause
+  // button drives it from its current value to animateTo over durationMs
+  // using requestAnimationFrame; the curve moves in place (y axis is locked).
+  const animParam = (() => {
+    for (const [si, s] of series.entries()) {
+      for (const p of s.params ?? []) {
+        if (p !== null && p !== undefined && p.animateTo !== undefined) {
+          return { si, param: p }
+        }
+      }
+    }
+    return null
+  })()
+  const [playing, setPlaying] = useState(false)
+  const [animProgress, setAnimProgress] = useState(0)
+  const animRef = useRef<number | null>(null)
+
+  useEffect(() => {
+    if (!playing || animParam === null) return
+    const from = params[`${animParam.si}:${animParam.param.name}`] ?? animParam.param.value
+    const to = animParam.param.animateTo!
+    const duration = animParam.param.durationMs ?? 4000
+    const start = performance.now()
+    const tick = (now: number): void => {
+      const t = Math.min(1, (now - start) / duration)
+      const eased = 1 - Math.pow(1 - t, 3) // easeOutCubic
+      const value = from + (to - from) * eased
+      setParams(prev => ({ ...prev, [`${animParam.si}:${animParam.param.name}`]: value }))
+      setAnimProgress(t)
+      if (t < 1) {
+        animRef.current = requestAnimationFrame(tick)
+      } else if (animParam.param.loop === true) {
+        setParams(prev => ({ ...prev, [`${animParam.si}:${animParam.param.name}`]: animParam.param.value }))
+        setAnimProgress(0)
+        animRef.current = requestAnimationFrame(() => setPlaying(p => p))
+      } else {
+        setPlaying(false)
+      }
+    }
+    animRef.current = requestAnimationFrame(tick)
+    return () => { if (animRef.current !== null) cancelAnimationFrame(animRef.current) }
+  }, [playing, animParam?.si, animParam?.param.name, animParam?.param.animateTo])
+
+  const xMin = view.xMin
+  const xMax = view.xMax
+  const lo = view.yMin
+  const hi = view.yMax
+  const plotW = WIDTH - PAD_L - PAD_R
+  const plotH = HEIGHT - PAD_T - PAD_B
+  const fromX = (px: number): number => xMin + ((px - PAD_L) / plotW) * (xMax - xMin)
+  const toX = (x: number): number => PAD_L + ((x - xMin) / (xMax - xMin)) * plotW
+  const toY = (y: number): number => PAD_T + (1 - (y - lo) / (hi - lo)) * plotH
+
+  // Sample with current parameter values, then convert to screen coordinates
+  // in one pass against the LOCKED y range — the `points` string changes with
+  // the parameters, so the curve's shape visibly responds to the slider.
+  const sampled = series.map((s, si) => {
+    const p: Record<string, number> = {}
+    for (const param of s.params ?? []) {
+      if (param === null || param === undefined) continue
+      p[param.name] = params[`${si}:${param.name}`] ?? param.value
+    }
+    const pts = sampleExpr(s.expr, xMin, xMax, SAMPLES, p)
+    return {
+      series: s,
+      points: pts.map(([x, y]) => `${toX(x).toFixed(2)},${toY(y).toFixed(2)}`).join(' '),
+    }
+  })
+
+  const xTicks = niceTicks(xMin, xMax)
+  const yTicks = niceTicks(lo, hi)
+  const hasData = sampled.some(p => p.points.length > 1)
+  const hasValidRange = Number.isFinite(xMin) && Number.isFinite(xMax) && xMax > xMin && Number.isFinite(hi) && Number.isFinite(lo) && hi > lo
+
+  // v2.9 draw shapes: line (polyline), area (fill to the locked baseline),
+  // scatter (dots only). Colors stay on the shared categorical palette.
+  const renderSeries = (s: PlotSeries, i: number, points: string): ReactNode => {
+    const color = seriesColor(i, sampled.length, s.color) ?? 'var(--dsw-alias-state-business-primary, #4f8ef7)'
+    const kind = s.kind ?? 'line'
+    if (kind === 'scatter') {
+      const coords = points === '' ? [] : points.split(' ').map(pt => {
+        const [x, y] = pt.split(',')
+        return [Number(x), Number(y)] as const
+      })
+      return (
+        <g key={i}>
+          {coords.map(([cx, cy], k) => <circle key={k} cx={cx} cy={cy} r={2.6} className={css.scatterDot} style={{ fill: color }} />)}
+        </g>
+      )
+    }
+    if (kind === 'area') {
+      if (points === '') return <Polyline key={i} points="" className={css.line} color={color} />
+      const firstX = points.slice(0, points.indexOf(' ')).split(',')[0]!
+      const lastX = points.slice(points.lastIndexOf(' ') + 1).split(',')[0]!
+      const baseY = toY(lo)
+      const poly = `${firstX},${baseY.toFixed(2)} ${points} ${lastX},${baseY.toFixed(2)}`
+      return <polygon key={i} points={poly} className={css.area} style={{ fill: color }} />
+    }
+    return <Polyline key={i} points={points} className={css.line} color={color} />
+  }
+
+  // Drag-to-pan and wheel-to-zoom on the SVG surface. Pan/zoom move the x
+  // window only; the y range stays locked so parameter changes stay visible.
+  const onPointerDown = (e: React.PointerEvent): void => {
+    dragRef.current = { startX: e.clientX, startY: e.clientY, xMin, xMax }
+    ;(e.target as Element).setPointerCapture?.(e.pointerId)
+  }
+  const onPointerMove = (e: React.PointerEvent): void => {
+    const d = dragRef.current
+    if (d === null) return
+    const span = d.xMax - d.xMin
+    const dx = ((d.startX - e.clientX) / plotW) * span
+    setView(prev => ({ xMin: d.xMin + dx, xMax: d.xMax + dx, yMin: prev.yMin, yMax: prev.yMax }))
+  }
+  const onPointerUp = (): void => { dragRef.current = null }
+  const onWheel = (e: React.WheelEvent): void => {
+    const span = xMax - xMin
+    const factor = e.deltaY > 0 ? 1.15 : 1 / 1.15
+    const next = span * factor
+    const rect = (e.currentTarget as Element).getBoundingClientRect()
+    const cx = fromX(((e.clientX - rect.left) / rect.width) * WIDTH)
+    const left = cx - ((cx - xMin) / span) * next
+    setView(prev => ({ xMin: left, xMax: left + next, yMin: prev.yMin, yMax: prev.yMax }))
+  }
+
+  const hasParams = series.some(s => (s.params?.length ?? 0) > 0)
+
+  return (
+    <div className={css.block} data-genui-plot>
+      {title !== undefined && <div className={css.title}>{title}</div>}
+      {hasData && hasValidRange ? (
+        <svg
+          width="100%"
+          viewBox={`0 0 ${WIDTH} ${HEIGHT}`}
+          role="img"
+          aria-label={title ?? 'function plot'}
+          className={css.surface}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onPointerLeave={onPointerUp}
+          onWheel={onWheel}
+        >
+          {/* y grid */}
+          {yTicks.map(t => (
+            <g key={`y${t}`}>
+              <line x1={PAD_L} x2={WIDTH - PAD_R} y1={toY(t)} y2={toY(t)} className={css.gridLine} />
+              <text x={PAD_L - 6} y={toY(t) + 4} className={css.tick} textAnchor="end">{formatTick(t)}</text>
+            </g>
+          ))}
+          {/* x grid */}
+          {xTicks.map(t => (
+            <g key={`x${t}`}>
+              <line x1={toX(t)} x2={toX(t)} y1={PAD_T} y2={HEIGHT - PAD_B} className={css.gridLine} />
+              <text x={toX(t)} y={HEIGHT - PAD_B + 14} className={css.tick} textAnchor="middle">{formatTick(t)}</text>
+            </g>
+          ))}
+          {/* axes */}
+          <line x1={PAD_L} x2={WIDTH - PAD_R} y1={HEIGHT - PAD_B} y2={HEIGHT - PAD_B} className={css.axis} />
+          <line x1={PAD_L} x2={PAD_L} y1={PAD_T} y2={HEIGHT - PAD_B} className={css.axis} />
+          {/* series */}
+          {sampled.map(({ series: s, points }, i) => renderSeries(s, i, points))}
+        </svg>
+      ) : (
+        <div className={css.empty}>
+          {series.map((s, i) => <div key={i} className={css.emptyRow}>{s.expr} — 无法绘制（表达式无效或范围非法）</div>)}
+        </div>
+      )}
+      {hasParams && (
+        <div className={css.sliders}>
+          <div className={css.slidersHead}>
+            <span className={css.slidersTitle}>参数调节</span>
+            <button
+              type="button"
+              className={css.resetBtn}
+              onClick={() => {
+                setPlaying(false)
+                const reset: Record<string, number> = {}
+                for (const [si, s] of series.entries()) {
+                  for (const p of s.params ?? []) {
+                    if (p !== null && p !== undefined) reset[`${si}:${p.name}`] = p.value
+                  }
+                }
+                setParams(reset)
+                setAnimProgress(0)
+              }}
+            >
+              ↺ 重置
+            </button>
+          </div>
+          {series.map((s, si) => (s.params ?? []).map(p => {
+            if (p === null || p === undefined) return null
+            const key = `${si}:${p.name}`
+            const value = params[key] ?? p.value
+            return (
+              <label key={key} className={css.sliderRow}>
+                <span className={css.sliderName}>{s.label ?? s.expr} · {p.name}</span>
+                <input
+                  type="range"
+                  className={css.slider}
+                  min={p.min ?? 0}
+                  max={p.max ?? 10}
+                  step={p.step ?? 0.1}
+                  value={value}
+                  onChange={e => {
+                    // Read the value synchronously: React 18 may null out
+                    // currentTarget after the handler in concurrent renders.
+                    const next = Number(e.currentTarget.value)
+                    setParams(prev => ({ ...prev, [key]: next }))
+                  }}
+                />
+                <span className={css.sliderValue}>{Math.round(value * 100) / 100}</span>
+              </label>
+            )
+          }))}
+        </div>
+      )}
+      {animParam !== null && (
+        <div className={css.animBar}>
+          <button
+            type="button"
+            className={css.playBtn}
+            onClick={() => {
+              if (playing) { setPlaying(false) }
+              else {
+                // Reset to the declared start value before playing.
+                setParams(prev => ({ ...prev, [`${animParam.si}:${animParam.param.name}`]: animParam.param.value }))
+                setAnimProgress(0)
+                setPlaying(true)
+              }
+            }}
+          >
+            {playing ? '⏸ 暂停' : '▶ 播放动画'}
+          </button>
+          {playing && (
+            <div className={css.animTrack}>
+              <div className={css.animFill} style={{ width: `${animProgress * 100}%` }} />
+            </div>
+          )}
+        </div>
+      )}
+      {(series.length > 1 || hasParams) && (
+        <div className={css.legend}>
+          {series.map((s, i) => (
+            <span key={i} className={css.legendItem}>
+              <span className={css.legendSwatch} style={{ background: seriesColor(i, series.length, s.color) ?? 'var(--dsw-alias-state-business-primary, #4f8ef7)' }} />
+              {s.label ?? s.expr}
+            </span>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+})

package/src/client/action-context.ts

@@ -0,0 +1,32 @@
+/**
+ * GenUI action context, plugin-owned.
+ *
+ * Contract hosts (`dsh-host-0812-contract` and later) ship the same context
+ * in `@deepseek-ai/dsh-client-ui-primitives` and MarkdownText installs the
+ * provider around fence renders — the renderer MUST consume that exact
+ * context instance so the host's action wiring reaches our components.
+ * Pristine hosts (the stock snapshot line) export no such symbol; the DOM
+ * render channel then falls back to the local context and installs its own
+ * provider (this package wraps every tree it mounts).
+ *
+ * Absent provider = v1 behavior: interactive components are display-only
+ * (their `action` is ignored). The hook never throws.
+ */
+import { createContext, useContext } from 'react'
+import type { Context } from 'react'
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+
+/** v2 action handler: component action + its collected data. */
+export type GenuiActionHandler = (action: string, payload: Record<string, unknown>) => void
+
+/** Local fallback context (pristine hosts). */
+const localContext = createContext<GenuiActionHandler | undefined>(undefined)
+
+/** Host-provided context when the deployment ships it, else the local one. */
+export const GenuiActionContext: Context<GenuiActionHandler | undefined> =
+  (primitives as unknown as { GenuiActionContext?: Context<GenuiActionHandler | undefined> }).GenuiActionContext ?? localContext
+
+/** Read the installed action handler, if any. */
+export function useGenuiAction(): GenuiActionHandler | undefined {
+  return useContext(GenuiActionContext)
+}

package/src/client/asset-echarts.ts

@@ -0,0 +1,25 @@
+/**
+ * ECharts asset-bundle entry: registers the echarts engine on
+ * `window.__GenuiAssets__.echarts`. Built as a standalone IIFE into
+ * `lib/assets/echarts.js` and served by the plugin's node-half route; loaded
+ * on demand by echarts-lazy when a spec contains an `echart` node.
+ * @module @changfenhuang/dsh-genui/client/asset-echarts
+ */
+import { init as echartsInit, type EChartsType, type EChartsCoreOption } from 'echarts'
+
+/** The engine surface registered by the echarts asset bundle. */
+export interface EChartsAssetApi {
+  /** Create an ECharts instance on `el`, apply `option`, return the instance. */
+  createChart: (el: HTMLElement, option: EChartsCoreOption, opts?: { height?: number }) => EChartsType
+}
+
+function createChart(el: HTMLElement, option: EChartsCoreOption, opts?: { height?: number }): EChartsType {
+  const initOpts = opts !== undefined && opts.height !== undefined ? { height: opts.height } : undefined
+  const instance = echartsInit(el, undefined, initOpts)
+  instance.setOption(option)
+  return instance
+}
+
+const win = globalThis as unknown as { __GenuiAssets__?: Record<string, unknown> }
+const assets = win.__GenuiAssets__ ?? (win.__GenuiAssets__ = {})
+assets.echarts = { createChart }

package/src/client/asset-loader.ts

@@ -0,0 +1,79 @@
+/**
+ * Asset-bundle loader: fetches one of the plugin's lazy engine bundles
+ * (`lib/assets/mermaid.js` / `lib/assets/three.js`) by script injection and
+ * hands back the engine surface the bundle registered on
+ * `window.__GenuiAssets__`.
+ *
+ * The bundles are served by the plugin's OWN node-half HTTP route
+ * (`/plugins/@changfenhuang/dsh-genui/assets/*`), registered through the host
+ * webserver service — no host source change needed, and the longest-prefix
+ * rule lets this route win over the generic `/plugins` bundle route. Each
+ * file is loaded at most once per page (promise memoized); a rejection is
+ * final for the page (the node's fallback UI takes over).
+ *
+ * The rev query rides the boot graph: the plugin's own row in
+ * `window.__DSH_BOOT__` carries the client bundle rev, so a plugin rebuild
+ * busts the asset cache together with the main bundle. Absent graph = no
+ * query; the route serves no-cache anyway.
+ * @module @changfenhuang/dsh-genui/client/asset-loader
+ */
+
+/** The plugin's entry id — mirrors the loader entry name (package name). */
+const PLUGIN_ID = '@changfenhuang/dsh-genui'
+
+/** Assets directory served by the node-half route. */
+const ASSET_DIR = `/plugins/${PLUGIN_ID}/assets`
+
+/** Boot graph shape read from `window.__DSH_BOOT__` (subset, defensive). */
+interface BootGraphLike {
+  entries?: Array<{ id?: string; rev?: string }>
+}
+
+/** The global the asset bundles register their engines on. */
+interface AssetGlobal {
+  __GenuiAssets__?: Record<string, unknown>
+}
+
+/** Resolve an asset URL, appending the bundle rev for cache busting when the
+ * boot graph exposes it. */
+export function assetUrl(file: string): string {
+  const graph = (window as unknown as { __DSH_BOOT__?: BootGraphLike }).__DSH_BOOT__
+  const rev = graph?.entries?.find(entry => entry.id === PLUGIN_ID)?.rev
+  return `${ASSET_DIR}/${file}${rev === undefined ? '' : `?rev=${rev}`}`
+}
+
+const pending = new Map<string, Promise<Record<string, unknown>>>()
+
+/**
+ * Load one asset bundle and return the engines it registered. Memoized per
+ * file: repeated requests (several mermaid nodes, re-renders) share one
+ * script load; a failed load stays failed for the page (the component shows
+ * its fallback).
+ * @param name - 'mermaid', 'three', or 'echarts'.
+ * @returns the registered engine surface.
+ */
+export function loadGenuiAsset<T>(name: 'mermaid' | 'three' | 'echarts'): Promise<T> {
+  const file = `${name}.js`
+  const existing = pending.get(file)
+  if (existing !== undefined) return existing as Promise<T>
+  const task = new Promise<T>((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = assetUrl(file)
+    script.async = true
+    script.onload = () => {
+      const global = (window as unknown as AssetGlobal).__GenuiAssets__ ?? {}
+      const api = global[name]
+      if (api === undefined) {
+        reject(new Error(`genui asset '${file}' loaded but registered no '${name}' engine`))
+        return
+      }
+      resolve(api as T)
+    }
+    script.onerror = () => {
+      reject(new Error(`genui asset '${file}' failed to load (host asset route missing?)`))
+    }
+    document.head.appendChild(script)
+  })
+  pending.set(file, task as unknown as Promise<Record<string, unknown>>)
+  return task
+}

package/src/client/asset-mermaid.ts

@@ -0,0 +1,13 @@
+/**
+ * Mermaid asset-bundle entry: registers the mermaid engine on
+ * `window.__GenuiAssets__.mermaid`. Built as a standalone IIFE into
+ * `lib/assets/mermaid.js` and served by the plugin's node-half route; loaded
+ * on demand by mermaid-lazy.
+ * @module @changfenhuang/dsh-genui/client/asset-mermaid
+ */
+import { renderMermaid } from './mermaid-core.ts'
+import { assertSafeSvg, repairMermaidSource } from './mermaid-safe.ts'
+
+const win = globalThis as unknown as { __GenuiAssets__?: Record<string, unknown> }
+const assets = win.__GenuiAssets__ ?? (win.__GenuiAssets__ = {})
+assets.mermaid = { assertSafeSvg, repairMermaidSource, renderMermaid }

package/src/client/asset-three.ts

@@ -0,0 +1,12 @@
+/**
+ * three.js asset-bundle entry: registers the scene renderer on
+ * `window.__GenuiAssets__.three`. Built as a standalone IIFE into
+ * `lib/assets/three.js` and served by the plugin's node-half route; loaded on
+ * demand by scene3d-lazy.
+ * @module @changfenhuang/dsh-genui/client/asset-three
+ */
+import { mountScene } from './scene3d-core.ts'
+
+const win = globalThis as unknown as { __GenuiAssets__?: Record<string, unknown> }
+const assets = win.__GenuiAssets__ ?? (win.__GenuiAssets__ = {})
+assets.three = { mountScene }