@lincyaw/addon-exec 0.0.0-stage → 1.0.0-rc.10

package/components/PmStepRun.tsx

@@ -0,0 +1,202 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { errorMessage } from '@lincyaw/kernel'
+import {
+  PmIconButton,
+  useStep,
+  useStepScope,
+  useMessages,
+  usePresentationMode,
+  useSectionConfig,
+  useService,
+  useStartReport,
+  useViewRole,
+} from '@lincyaw/host'
+import { markLine, MESSAGES } from '../src/client/index.ts'
+import {
+  configuredTimeout,
+  EXEC_ID,
+  frameAt,
+  stringArgs,
+  TRACER,
+} from '../src/domain/index.ts'
+import type { Trace } from '../src/domain/index.ts'
+import './PmStepRun.css'
+export default function PmStepRun({
+  lang = 'python',
+  code = '',
+  params,
+  timeout,
+  steps,
+  children,
+}: {
+  lang?: string
+  code?: string
+  params?: Record<string, string | number | boolean>
+  timeout?: number
+  steps?: number
+  children?: ReactNode
+}) {
+  const tracer = useService(TRACER),
+    report = useStartReport(),
+    config = useSectionConfig(EXEC_ID),
+    t = useMessages(MESSAGES)
+  const root = useRef<HTMLDivElement>(null),
+    source = useRef<HTMLDivElement>(null)
+  const [near, setNear] = useState(false),
+    [trace, setTrace] = useState<Trace>(),
+    [local, setLocal] = useState<number>()
+  const hostStep = useStep(),
+    scope = useStepScope(),
+    role = useViewRole()
+  const expanded = !Number.isFinite(hostStep),
+    lazy = usePresentationMode() === 'document'
+  const count = steps ?? trace?.events.length ?? 0
+  const traced = trace?.error === undefined ? trace?.events.length : undefined
+  const last = traced ?? count
+  const sectionStep = Math.max(0, Math.min(count, scope.localStepAt(hostStep)))
+  const step = expanded ? (local ?? last) : sectionStep
+  const frame = trace ? frameAt(trace, step) : undefined
+  const state = trace
+    ? trace.error === undefined
+      ? 'ready'
+      : 'failed'
+    : !tracer && report
+      ? 'unavailable'
+      : 'loading'
+  const authoring = role === 'presenter' || import.meta.env.DEV
+  const wanted = !lazy || near || (!expanded && sectionStep > 0)
+  useEffect(() => {
+    if (!lazy || !root.current || typeof IntersectionObserver === 'undefined') {
+      setNear(true)
+      return
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setNear(true)
+          observer.disconnect()
+        }
+      },
+      { rootMargin: '200px 0px' },
+    )
+    observer.observe(root.current)
+    return () => observer.disconnect()
+  }, [lazy])
+  const timeoutMs = timeout ?? configuredTimeout(config)
+  useEffect(() => {
+    if (!tracer || !wanted) return
+    let disposed = false
+    void tracer
+      .trace({
+        lang,
+        code,
+        args: stringArgs(params),
+        timeoutMs,
+      })
+      .then((result) => {
+        if (!disposed) setTrace(result)
+      })
+      .catch((error) => {
+        if (!disposed)
+          setTrace({ events: [], truncated: false, error: errorMessage(error) })
+      })
+    return () => {
+      disposed = true
+    }
+  }, [tracer, wanted, lang, code, params, timeoutMs])
+  useLayoutEffect(
+    () => markLine(source.current, frame?.line, 'pm-step-run__line'),
+    [frame?.line, children, code],
+  )
+  const go = (target: number) => setLocal(Math.max(0, Math.min(last, target)))
+  return (
+    <div
+      ref={root}
+      className="pm-step-run"
+      data-state={state}
+      data-steps={count}
+      data-step={frame?.step}
+      data-line={frame?.line}
+    >
+      <div ref={source} className="pm-step-run__source">
+        {children ?? (
+          <pre>
+            <code>
+              {code.split('\n').map((text, i) => (
+                <span key={i}>
+                  <span className="line">{text}</span>
+                  {'\n'}
+                </span>
+              ))}
+            </code>
+          </pre>
+        )}
+      </div>
+      <div className="pm-step-run__side">
+        <div className="pm-step-run__status">
+          {state === 'loading' ? (
+            t.tracing
+          ) : state === 'unavailable' ? (
+            t.unavailable
+          ) : state === 'failed' ? (
+            t.traceFailed
+          ) : (
+            <>
+              {t.stepOf(frame?.step ?? 0, traced ?? 0)}
+              {frame?.line ? t.atLine(frame.line) : ''}
+              {trace?.truncated ? t.truncated : ''}
+              {authoring &&
+                (steps !== undefined &&
+                traced !== undefined &&
+                traced !== steps ? (
+                  <div className="pm-step-run__warning">
+                    {t.stepsMismatch(steps, traced)}
+                  </div>
+                ) : steps === undefined ? (
+                  <div className="pm-step-run__warning">
+                    {t.stepsMissing(traced ?? 0)}
+                  </div>
+                ) : null)}
+            </>
+          )}
+        </div>
+        {expanded && state === 'ready' && (
+          <div
+            className="pm-step-run__stepper"
+            role="group"
+            aria-label={t.stepper}
+            onKeyDown={(e) => e.stopPropagation()}
+          >
+            <PmIconButton
+              icon="chevron-left"
+              label={t.previousStep}
+              small
+              disabled={(frame?.step ?? 0) <= 0}
+              onClick={() => go((frame?.step ?? 0) - 1)}
+            />
+            <input
+              type="range"
+              min="0"
+              max={last}
+              value={frame?.step ?? 0}
+              aria-label={t.stepper}
+              aria-valuetext={t.stepOf(frame?.step ?? 0, last)}
+              onChange={(e) => go(Number(e.target.value))}
+            />
+            <PmIconButton
+              icon="chevron-right"
+              label={t.nextStep}
+              small
+              disabled={(frame?.step ?? 0) >= last}
+              onClick={() => go((frame?.step ?? 0) + 1)}
+            />
+          </div>
+        )}
+        <pre className="pm-step-run__output">
+          {trace?.error ?? frame?.output}
+        </pre>
+      </div>
+    </div>
+  )
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@lincyaw/addon-exec",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.10",
+  "description": "Presmium plugin: run panels for code, step-by-step execution and recorded outputs; Python in the browser with Pyodide",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/addon-exec"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/addon-exec#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./domain": "./src/domain/index.ts",
+    "./client": "./src/client/index.ts",
+    "./presmium": "./src/node/presmium.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSES",
+    "components",
+    "src"
+  ],
+  "dependencies": {
+    "diff": "^9.0.0",
+    "dompurify": "3.4.17",
+    "pyodide": "^314.0.7",
+    "sucrase": "^3.35.1",
+    "yaml": "^2.9.1"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "@lincyaw/host": "^1.0.0-rc.10",
+    "@lincyaw/kernel": "^1.0.0-rc.10"
+  },
+  "devDependencies": {
+    "react": "18.3.1",
+    "@types/react": "18.3.28",
+    "@lincyaw/cli": "1.0.0-rc.10",
+    "@lincyaw/host": "1.0.0-rc.10",
+    "@lincyaw/kernel": "1.0.0-rc.10"
+  }
 }

package/src/client/RunOutputs.css

@@ -0,0 +1,21 @@
+.pm-run-panel__stdout,
+.pm-run-panel__stderr {
+  margin: 0;
+  max-height: 8em;
+  overflow: auto;
+  font-family: var(--pm-font-mono);
+  font-size: 1.1em;
+  line-height: 1.6;
+  white-space: pre-wrap;
+}
+.pm-run-panel__stderr {
+  color: var(--pm-color-danger);
+}
+.pm-run-panel__image {
+  max-width: 100%;
+  max-height: 20em;
+  object-fit: contain;
+}
+.pm-run-panel__html {
+  overflow: auto;
+}

package/src/client/RunOutputs.tsx

@@ -0,0 +1,69 @@
+import { Fragment, useEffect, useState } from 'react'
+import { useMessages } from '@lincyaw/host'
+import type { RunResult } from '@lincyaw/kernel'
+import { MESSAGES } from './messages.ts'
+import { displayItem } from './outputs.ts'
+import './RunOutputs.css'
+export default function RunOutputs({
+  result,
+  hideError = false,
+}: {
+  result: RunResult
+  hideError?: boolean
+}) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  const t = useMessages(MESSAGES)
+  const outputs =
+    result.outputs && result.source !== 'recorded'
+      ? result.outputs.map((output) => displayItem(output, { html: mounted }))
+      : [
+          {
+            kind: 'stream' as const,
+            name: 'stdout' as const,
+            text: result.stdout,
+          },
+          {
+            kind: 'stream' as const,
+            name: 'stderr' as const,
+            text: result.stderr,
+          },
+        ]
+  return (
+    <>
+      {outputs.map((item, i) => {
+        if (item.kind === 'image')
+          return (
+            <img
+              key={i}
+              className="pm-run-panel__image"
+              src={item.src}
+              alt=""
+            />
+          )
+        if (item.kind === 'html')
+          return (
+            <div
+              key={i}
+              className="pm-run-panel__html"
+              dangerouslySetInnerHTML={{ __html: item.html }}
+            />
+          )
+        const kind =
+          item.kind === 'stream'
+            ? item.name
+            : item.kind === 'error' || item.kind === 'dropped-image'
+              ? 'stderr'
+              : 'stdout'
+        const text = item.kind === 'dropped-image' ? t.droppedImage : item.text
+        return (
+          <Fragment key={i}>
+            {text && !(hideError && kind === 'stderr') && (
+              <pre className={`pm-run-panel__${kind}`}>{text}</pre>
+            )}
+          </Fragment>
+        )
+      })}
+    </>
+  )
+}

package/src/client/StepMark.css

@@ -0,0 +1,3 @@
+.pm-step-mark {
+  display: none;
+}

package/src/client/StepMark.tsx

@@ -0,0 +1,12 @@
+import { useContext, useEffect } from 'react'
+import { useStepState } from '@lincyaw/host'
+import { STEP_MARKS } from './step-marks.ts'
+export default function StepMark({ step }: { step: number }) {
+  const register = useContext(STEP_MARKS)
+  const state = useStepState({ from: step })
+  useEffect(
+    () => register?.(step, state),
+    [register, step, state.reached, state.active],
+  )
+  return null
+}

package/src/client/env.d.ts

@@ -0,0 +1,13 @@
+interface ImportMetaEnv {
+  BASE_URL: string
+  DEV: boolean
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+
+declare module '*.py?raw' {
+  const source: string
+  export default source
+}

package/src/client/feedback.ts

@@ -0,0 +1,69 @@
+import type { ExecutorRouter, RunRequest, RunResult } from '@lincyaw/kernel'
+import { mimeText } from '../domain/index.ts'
+
+const LIMIT = 8
+const TEXT_LIMIT = 2000
+
+interface Feedback {
+  id: number
+  at: number
+  type: 'run' | 'reset-session'
+  state: 'running' | 'succeeded' | 'failed' | 'timed-out' | 'reset'
+  section?: string
+  block?: string
+  lang?: string
+  session?: string
+  executor?: string
+  exitCode?: number | null
+  source?: 'live' | 'recorded'
+  durationMs?: number
+  stdout?: string
+  stderr?: string
+  value?: string
+  displayTypes?: string[]
+  truncated?: boolean
+}
+
+function resultInfo(result: RunResult): Partial<Feedback> {
+  const values = result.outputs?.flatMap(output => output.output_type === 'execute_result'
+    ? [output.data['text/plain'] ?? output.data['text/markdown'] ?? output.data['application/json']]
+    : []) ?? []
+  const value = values.map(value => mimeText(value)).join('\n')
+  const displayTypes = [...new Set(result.outputs?.flatMap(output => output.output_type === 'execute_result' || output.output_type === 'display_data' ? Object.keys(output.data) : []) ?? [])]
+  return {
+    state: result.timedOut ? 'timed-out' : result.ok ? 'succeeded' : 'failed',
+    executor: result.executorId,
+    exitCode: result.exitCode,
+    source: result.source,
+    durationMs: result.durationMs,
+    stdout: result.stdout.slice(0, TEXT_LIMIT),
+    stderr: result.stderr.slice(0, TEXT_LIMIT),
+    ...value ? { value: value.slice(0, TEXT_LIMIT) } : {},
+    ...displayTypes.length ? { displayTypes } : {},
+    ...[result.stdout, result.stderr, value].some(text => text.length > TEXT_LIMIT) ? { truncated: true } : {},
+  }
+}
+
+/** Status follows the shared execution boundary, so every browser executor reports the same way. */
+export function withRuntimeFeedback(router: ExecutorRouter): { executor: ExecutorRouter, read(): { recent: Feedback[] } } {
+  let sequence = 0
+  let recent: Feedback[] = []
+  const add = (entry: Feedback) => { recent = [...recent, entry].slice(-LIMIT) }
+  return {
+    read: () => ({ recent }),
+    executor: {
+      ...router,
+      async run(request: RunRequest, signal?: AbortSignal) {
+        const id = ++sequence
+        add({ id, at: Date.now(), type: 'run', state: 'running', lang: request.lang, ...request.place ? { section: request.place.section, block: request.place.block } : {}, ...request.session ? { session: request.session } : {} })
+        const result = await router.run(request, signal)
+        recent = recent.map(entry => entry.id === id ? { ...entry, ...resultInfo(result) } : entry)
+        return result
+      },
+      async endSession(session) {
+        await router.endSession?.(session)
+        add({ id: ++sequence, at: Date.now(), type: 'reset-session', state: 'reset', session })
+      },
+    },
+  }
+}

package/src/client/format.ts

@@ -0,0 +1,30 @@
+const NAMES: Record<string, string> = {
+  'python': 'Python',
+  'py': 'Python',
+  'python3': 'Python',
+  'javascript': 'JavaScript',
+  'js': 'JavaScript',
+  'typescript': 'TypeScript',
+  'ts': 'TypeScript',
+  'wgsl': 'WGSL',
+  'c': 'C',
+  'cpp': 'C++',
+  'c++': 'C++',
+  'ruby': 'Ruby',
+  'rb': 'Ruby',
+  'sql': 'SQL',
+  'r': 'R',
+  'julia': 'Julia',
+  'bash': 'Bash',
+  'sh': 'Shell',
+  'shell': 'Shell',
+}
+
+export function languageName(lang: string): string {
+  return NAMES[lang.toLowerCase()] ?? lang
+}
+
+export function seconds(ms: number): string {
+  const s = Math.max(0, ms) / 1000
+  return s < 10 ? s.toFixed(2) : s < 100 ? s.toFixed(1) : String(Math.round(s))
+}

package/src/client/index.ts

@@ -0,0 +1,14 @@
+export { execPlugin } from './plugin.ts'
+export { messages, MESSAGES } from './messages.ts'
+export type { ExecMessages } from './messages.ts'
+export { languageName, seconds } from './format.ts'
+export { runsInOf } from './runs-in.ts'
+export type { RunsIn } from './runs-in.ts'
+export { createPyodideExecutor, PYODIDE_EXECUTOR_ID } from './pyodide/executor.ts'
+export type { PyodideExecutor, PyodideExecutorOptions } from './pyodide/executor.ts'
+export { BROWSER_SCRIPT_EXECUTOR_ID, createScriptExecutor } from './script/executor.ts'
+export type { ScriptExecutor } from './script/executor.ts'
+export { whenService } from './when-service.ts'
+export { markLine, STEP_MARKS } from './step-marks.ts'
+export type { RegisterStepMark } from './step-marks.ts'
+export { useSlideSpaceBelow } from './slide-fit.ts'

package/src/client/messages.ts

@@ -0,0 +1,102 @@
+import { currentLocale } from '@lincyaw/host'
+import type { Catalog } from '@lincyaw/host'
+
+const zhCN = {
+  run: '运行',
+  rerun: '重新运行',
+  running: '正在运行…',
+  unavailable: '此处无法运行代码',
+  timedOut: '运行超时',
+  failed: '运行失败',
+  recordedBadge: (reason: string) => `预录输出 · ${reason}`,
+  recordedLine: (reason: string) => `预录输出（${reason}）`,
+  recordedOutput: '预录输出',
+  runHint: (icon: string) => `按 ${icon} 运行这段代码`,
+  runsIn: {
+    browser: '浏览器中运行',
+    machine: '本机运行',
+    remote: (name: string) => `在远端环境 ${name} 中运行`,
+    environment: (name: string) => `在环境 ${name} 中运行`,
+  },
+  output: '输出',
+  outputTook: (seconds: string) => `输出 · ${seconds} 秒`,
+  droppedImage: '图片输出的数据不是 base64，未显示',
+  gpuUnavailable: (detail: string) => (/no gpu adapter/i.test(detail) ? '没有可用的 GPU 适配器' : /no webgpu/i.test(detail) ? '浏览器没有 WebGPU' : `GPU 不可用：${detail}`),
+  recorded: '预录',
+  succeeded: '成功',
+  failedShort: '失败',
+  compare: (before: number, after: number) => `对比 #${before} → #${after}`,
+  argChange: (name: string, before: string, after: string) => `${name}：${before} → ${after}`,
+  tracing: '正在追踪执行…',
+  traceFailed: '追踪失败',
+  stepOf: (step: number, total: number) => `第 ${step} / ${total} 步`,
+  atLine: (line: number) => ` · 第 ${line} 行`,
+  truncated: '（已截断）',
+  stepsMismatch: (declared: number, traced: number) => `steps 声明为 ${declared}，实际执行 ${traced} 行`,
+  stepsMissing: (traced: number) => `未声明 steps（应为 ${traced}），直接打开某一步时无法恢复`,
+  cancelled: '已取消',
+  runTimeout: (ms: number) => `执行超过 ${ms} ms，已停止`,
+  runtimeCrashed: (runtime: string, error: string) => `无法运行 ${runtime} 代码：${error}`,
+  loadTimeout: (runtime: string, ms: number) => `${runtime} 运行时 ${ms} ms 内未加载完成，已停止`,
+  noExecutor: (lang: string) => `此处无法运行 ${lang} 代码`,
+  executorUnavailable: (id: string, lang: string) => `运行环境 ${id} 不可用（未设置，或不能运行 ${lang}）`,
+  resetSession: '重置会话',
+  executorCrashed: (_id: string, error: string) => `无法运行代码：${error}`,
+  stepper: '逐行执行的步骤',
+  previousStep: '上一步',
+  nextStep: '下一步',
+}
+
+export type ExecMessages = typeof zhCN
+
+const en: ExecMessages = {
+  run: 'Run',
+  rerun: 'Run Again',
+  running: 'Running…',
+  unavailable: 'Code can’t run here',
+  timedOut: 'timed out',
+  failed: 'run failed',
+  recordedBadge: reason => `Recorded output · ${reason}`,
+  recordedLine: reason => `Recorded output (${reason})`,
+  recordedOutput: 'Recorded output',
+  runHint: icon => `Press ${icon} to run this code`,
+  runsIn: {
+    browser: 'runs in the browser',
+    machine: 'runs on this machine',
+    remote: name => `runs in the remote environment ${name}`,
+    environment: name => `runs in the environment ${name}`,
+  },
+  output: 'Output',
+  outputTook: seconds => `Output · ${seconds} s`,
+  droppedImage: 'The picture output does not hold base64 data and is not shown',
+  gpuUnavailable: detail => (/no gpu adapter/i.test(detail) ? 'No GPU adapter is available' : /no webgpu/i.test(detail) ? 'This browser has no WebGPU' : `The GPU is unavailable: ${detail}`),
+  recorded: 'recorded',
+  succeeded: 'ok',
+  failedShort: 'failed',
+  compare: (before, after) => `Compare #${before} → #${after}`,
+  argChange: (name, before, after) => `${name}: ${before} → ${after}`,
+  tracing: 'Tracing the run…',
+  traceFailed: 'Tracing failed',
+  stepOf: (step, total) => `Step ${step} / ${total}`,
+  atLine: line => ` · line ${line}`,
+  truncated: ' (truncated)',
+  stepsMismatch: (declared, traced) => `steps is declared as ${declared}, but ${traced} lines ran`,
+  stepsMissing: traced => `steps is not declared (it should be ${traced}); opening a step directly cannot restore it`,
+  cancelled: 'Canceled',
+  runTimeout: ms => `Stopped after ${ms} ms`,
+  runtimeCrashed: (runtime, error) => `Couldn’t run the ${runtime} code: ${error}`,
+  loadTimeout: (runtime, ms) => `The ${runtime} runtime did not load within ${ms} ms; stopped`,
+  noExecutor: lang => `${lang} code can’t run here`,
+  executorUnavailable: (id, lang) => `The run environment ${id} is unavailable (not set up, or it can’t run ${lang})`,
+  resetSession: 'Reset Session',
+  executorCrashed: (_id, error) => `Couldn’t run the code: ${error}`,
+  stepper: 'Steps of the run',
+  previousStep: 'Previous Step',
+  nextStep: 'Next Step',
+}
+
+export const MESSAGES: Catalog<ExecMessages> = { 'zh-CN': zhCN, en }
+
+export function messages(): ExecMessages {
+  return MESSAGES[currentLocale()]
+}

package/src/client/outputs.ts

@@ -0,0 +1,29 @@
+import type { RunOutput } from '@lincyaw/kernel'
+import DOMPurify from 'dompurify'
+import { mimeText } from '../domain/index.ts'
+
+export type DisplayItem =
+  | { kind: 'stream', name: 'stdout' | 'stderr', text: string }
+  | { kind: 'error', text: string }
+  | { kind: 'image', src: string }
+  | { kind: 'dropped-image' }
+  | { kind: 'html', html: string }
+  | { kind: 'text', text: string }
+
+const IMAGES = ['image/png', 'image/jpeg', 'image/gif']
+const BASE64 = /^[A-Za-z0-9+/=]*$/
+
+/** What to show of one output: an image, sanitized HTML (only where `html` allows it) or text, in this order of preference. */
+export function displayItem(output: RunOutput, options: { html: boolean }): DisplayItem {
+  if (output.output_type === 'stream') return { kind: 'stream', name: output.name, text: mimeText(output.text) }
+  if (output.output_type === 'error') return { kind: 'error', text: output.traceback.join('\n') || `${output.ename}: ${output.evalue}` }
+  const { data } = output
+  const image = IMAGES.find(type => data[type] !== undefined)
+  if (image) {
+    const base64 = mimeText(data[image], 2).replace(/\s/g, '')
+    return BASE64.test(base64) ? { kind: 'image', src: `data:${image};base64,${base64}` } : { kind: 'dropped-image' }
+  }
+  if (data['image/svg+xml'] !== undefined) return { kind: 'image', src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(mimeText(data['image/svg+xml'], 2))}` }
+  if (data['text/html'] !== undefined && options.html) return { kind: 'html', html: DOMPurify.sanitize(mimeText(data['text/html'], 2)) }
+  return { kind: 'text', text: mimeText(data['text/markdown'] ?? data['text/plain'] ?? data['application/json'] ?? data['text/latex'], 2) }
+}