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

package/src/ir.ts

@@ -0,0 +1,367 @@
+import type {
+  AnchorLockFile,
+  AnchorResolverRegistry,
+  AnchorString,
+  ExecuteConfig,
+  Executor,
+  Finding,
+  ResolutionStatus,
+  RunResult,
+  ServiceToken,
+  SourceReader,
+} from './contracts.ts'
+
+export const IR_VERSION = 1
+
+export type RendererId = string
+
+export interface MdastNode {
+  type: string
+  children?: MdastNode[]
+  value?: string
+  [key: string]: unknown
+}
+
+export interface SourcePos {
+  file: string
+  line: number
+  endLine?: number
+  format?: 'json'
+  pointer?: string
+}
+
+/** Compiler-owned identity of the exact canonical authoring entry behind a runtime snapshot. */
+export interface CanonicalSource {
+  documentId: string
+  version: string
+  fingerprint: string
+}
+
+export interface IRDocument {
+  ir: typeof IR_VERSION
+  /** Read-only provenance, never authored metadata or editable document content. */
+  source?: CanonicalSource
+  meta: {
+    title: string
+    entry: string
+    lang?: string
+    translationOf?: { entry: string, digest: string }
+    [key: string]: unknown
+  }
+  config: {
+    plugins: string[]
+    presmium: Record<string, unknown>
+    renderers: Record<RendererId, Record<string, unknown>>
+    execute?: ExecuteConfig
+    translations?: Record<string, string>
+  }
+  sections: IRSection[]
+  diagnostics: Finding[]
+  production?: import('./contracts/document.ts').Production
+  /** Canonical media declarations available to production renderers without reopening authoring JSON. */
+  productionAssets?: Record<string, import('./contracts/document.ts').Asset>
+}
+
+export interface IRSection {
+  id: string
+  index: number
+  title: string
+  depth: number
+  source: SourcePos
+  steps: number
+  stepMap?: number[]
+  stepIds?: string[]
+  /** Display-only canonical narration by stable step, without an audio or timing claim. */
+  stepNarrations?: Record<string, { id: string, text: string }[]>
+  /** Exact canonical per-step caption basis, independent of overall source version and preceding steps. */
+  captionSources?: Record<string, string>
+  hints: Record<RendererId, Record<string, unknown>>
+  config?: Record<string, Record<string, unknown>>
+  blocks: IRBlock[]
+  audience?: string[]
+}
+
+export type BlockRole = 'visual' | 'narration'
+
+export interface IRBlock {
+  id: string
+  role: BlockRole
+  at: number
+  until?: number
+  span?: number
+  only?: RendererId[]
+  audience?: string[]
+  source: SourcePos
+  node: IRNode
+  /** Complete resolved state at every section step, derived from the authoring graph. */
+  stepStates?: { visible: boolean, state?: string, parameters?: Record<string, unknown>, assets?: Record<string, string>, localStep: number }[]
+}
+
+export type IRNode = MarkdownNode | CodeNode | ComponentNode
+
+export interface MarkdownNode {
+  type: 'markdown'
+  mdast: MdastNode
+  reveal?: 'items'
+  /** An explicitly authored step's speech starts with, or after, its animation. */
+  narration?: { mode: 'during' | 'after' }
+}
+
+export interface CodeOrigin {
+  anchor: AnchorString
+  file: string
+  startLine: number
+  endLine: number
+  pin?: string
+  permalink?: string
+  status: ResolutionStatus
+  units?: Record<string, { startLine: number; endLine: number }>
+  drift?: 'synced' | 'drifted'
+}
+
+export interface RunSpec {
+  lang: string
+  args?: Record<string, string>
+  stdin?: string
+  timeoutMs?: number
+  executor?: string
+  when: 'compile' | 'live' | 'both'
+  session?: string
+}
+
+export interface RecordedRun extends RunResult {
+  cacheKey: string
+}
+
+export interface CodeVariant {
+  label: string
+  value: string
+  permalink?: string
+  startLine?: number
+  endLine?: number
+}
+
+export interface CodeNode {
+  type: 'code'
+  lang: string
+  value: string
+  title?: string
+  origin?: CodeOrigin
+  highlight?: number[][]
+  run?: RunSpec
+  outputs?: RecordedRun[]
+  variants?: CodeVariant[]
+  echo?: false
+  /** Structured source references for the resolver pass, independent of authoring syntax. */
+  reference?: { anchor: AnchorString, pin?: string, repo?: string, highlightRegions?: string[], variants?: { anchor?: AnchorString, pin?: string, repo?: string, label: string, value?: string }[] }
+}
+
+export interface ComponentNode {
+  type: 'component'
+  plugin: string
+  name: string
+  props: Record<string, unknown>
+  children?: IRBlock[]
+  ownsCode?: boolean
+  fallback?: MdastNode
+  assets?: Record<string, string>
+  layer?: 'overlay'
+  durations?: number[]
+  /** The authored code that defines this component instance, when supplied by its plugin. */
+  definition?: { file: string, language: string, exportName?: string }
+}
+
+export type DirectiveOptionType = 'string' | 'number' | 'boolean' | 'list'
+
+export interface DirectiveInput {
+  name: string
+  arg?: string
+  options: Record<string, unknown>
+  body: string
+}
+
+export interface DirectiveContext {
+  file: string
+  deckDir: string
+  workspaceRoot: string
+  lang?: string
+  config: Record<string, unknown>
+  source: SourcePos
+  parse(markdown: string): MdastNode
+  report(finding: Finding): void
+  watch(...files: string[]): void
+}
+
+export interface DirectiveResult {
+  node: IRNode
+  role?: BlockRole
+  span?: number
+}
+
+export interface RoleInput {
+  name: string
+  value: string
+  options: Record<string, unknown>
+}
+
+export interface RoleSpec {
+  name: string
+  options?: Record<string, DirectiveOptionType>
+  children?(input: RoleInput, ctx: DirectiveContext): MdastNode[]
+}
+
+export interface PresmiumRoleNode extends MdastNode {
+  type: 'presmiumRole'
+  plugin: string
+  name: string
+  options: Record<string, unknown>
+  children: MdastNode[]
+}
+
+export interface DirectiveSpec {
+  name: string
+  arg?: boolean | 'anchor'
+  body?: boolean
+  options?: Record<string, DirectiveOptionType>
+  toIR(input: DirectiveInput, ctx: DirectiveContext): DirectiveResult | Promise<DirectiveResult>
+}
+
+export interface RunCache {
+  get(key: string): RecordedRun | undefined
+  set(key: string, run: RecordedRun): void
+}
+
+export interface PassContext {
+  deckDir: string
+  workspaceRoot: string
+  lang?: string
+  src: SourceReader
+  resolvers: AnchorResolverRegistry
+  lock: AnchorLockFile
+  executors: Executor[]
+  cache: RunCache
+  config: Record<string, unknown>
+  configFor(section: IRSection): Record<string, unknown>
+  report(finding: Finding): void
+  watch(...files: string[]): void
+  service?<T>(token: ServiceToken<T>): T | undefined
+}
+
+export interface IRPass {
+  name: string
+  order?: number
+  after?: 'execute'
+  run(doc: IRDocument, ctx: PassContext): void | Promise<void>
+}
+
+export type Support = 'full' | 'degraded' | 'none'
+
+export interface RenderContext {
+  deckDir: string
+  workspaceRoot: string
+  outDir: string
+  workDir: string
+  config: Record<string, unknown>
+  extensions: BoundRendererExtension[]
+  plugins: string[]
+  pluginDirs: Record<string, string>
+  lang?: string
+  renderers: RendererId[]
+  base: string
+  nodeVitePlugins?: NodeVitePlugin[]
+  extensionFor(node: ComponentNode): ((node: ComponentNode, block: IRBlock) => unknown) | undefined
+  portable(value: unknown, from: string): unknown
+  localAsset(source: SourcePos, url: string): LocalAsset | undefined
+  documentLink?(source: SourcePos, url: string): DocumentLink | undefined
+  report(finding: Finding): void
+  /** A line of the build's output (a tool's), for the job that runs it; renderers that start tools give theirs. */
+  log?(line: string): void
+  service?<T>(token: ServiceToken<T>): T | undefined
+  translations?: { lang: string, doc: IRDocument }[]
+  server?: { url: string }
+  preview?: { origins: string[] }
+}
+
+export interface NodeVitePlugin {
+  id: string
+  entry: string
+  config: Record<string, unknown>
+}
+
+export interface LocalAsset {
+  file: string
+  name: string
+  directory?: boolean
+}
+
+export interface DocumentLink {
+  dir: string
+  fragment?: string
+}
+
+export interface RenderOutput {
+  outDir: string
+  skipped: { section: string; block: string; reason: string }[]
+}
+
+export interface RenderDevServer {
+  url: string
+  update(doc: IRDocument): Promise<void>
+  close(): Promise<void>
+}
+
+export interface Renderer {
+  id: RendererId
+  site?: boolean
+  support(node: IRNode, extensions: BoundRendererExtension[]): Support
+  build(doc: IRDocument, ctx: RenderContext): Promise<RenderOutput>
+  dev?(doc: IRDocument, ctx: RenderContext): Promise<RenderDevServer>
+  buildSite?(site: SiteSpec, ctx: RenderContext): Promise<RenderOutput>
+  devSite?(site: SiteSpec, ctx: RenderContext, compile: (dir: string) => Promise<IRDocument>): Promise<SiteDevServer>
+}
+
+export interface SiteDocument {
+  dir: string
+  title: string
+  description?: string
+  lang?: string
+  tags?: string[]
+  doc?: IRDocument
+  translations?: { lang: string, doc: IRDocument }[]
+  nodeVitePlugins?: NodeVitePlugin[]
+}
+
+export interface SiteSpec {
+  title: string
+  documents: SiteDocument[]
+  home?: string
+  config: Record<string, unknown>
+}
+
+export interface SiteDevServer {
+  url: string
+  update(dir: string, doc: IRDocument): Promise<void>
+  /** Starts the dev server of document `dir` ahead of its first request (the author is about to open it); may decline. */
+  warm?(dir: string): Promise<void>
+  /** The origin of the dev server that serves `path` (started on first use), so that a host forwards to it directly. */
+  target?(path: string): Promise<string>
+  /**
+   * The address (below the site's URL) of the workbench's viewer app showing document `dir`, once the app (prebuilt for
+   * the workspace's plugins) and the document's own bundle are built: they are started when missing, and waited for a
+   * while with `wait`. Undefined until then, and for a document whose plugins the app cannot run (its dev server shows it).
+   * With `wait`, a build still running after the wait rejects with `PreviewPreparing`; a failed build with its reason.
+   */
+  app?(dir: string, wait?: boolean): Promise<string | undefined>
+  close(): Promise<void>
+}
+
+export type ComponentRenderer = (node: ComponentNode, block: IRBlock, ctx: RenderContext) => unknown
+
+export interface RendererContribution {
+  components?: Record<string, ComponentRenderer>
+}
+
+export interface BoundRendererExtension {
+  plugin: string
+  components?: Record<string, (node: ComponentNode, block: IRBlock) => unknown>
+}

package/src/jupyter-kernel.ts

@@ -0,0 +1,9 @@
+import { isRecord } from './errors.ts'
+import { languageId } from './execution.ts'
+
+/** The language of the notebook's Jupyter kernel, as `renderers.notebook.kernel` names it (a kernel name or `{ name, language }`); default Python. */
+export function jupyterKernelLanguage(kernel: unknown): string {
+  if (typeof kernel === 'string' && kernel) return languageId(kernel.replace(/[-\d.]+$/, '') || kernel)
+  if (isRecord(kernel) && typeof kernel.language === 'string') return languageId(kernel.language)
+  return 'python'
+}

package/src/kernel.ts

@@ -0,0 +1,190 @@
+import { KERNEL_VERSION } from './contracts.ts'
+import type {
+  EnvironmentSpec,
+  EventBus,
+  KernelEvent,
+  Logger,
+  PluginContext,
+  PluginDefinition,
+  PluginReport,
+  PresentationMode,
+  ServiceToken,
+  StartReport,
+} from './contracts.ts'
+import { errorMessage, isRecord } from './errors.ts'
+import { createEventBus } from './events.ts'
+import { prefixedLogger } from './logging.ts'
+import { ServiceRegistry } from './services.ts'
+
+export interface KernelOptions {
+  mode: PresentationMode
+  config?: Record<string, unknown>
+  log?: Logger
+  events?: EventBus
+  environments?: Record<string, EnvironmentSpec>
+}
+
+export class Kernel {
+  readonly version = KERNEL_VERSION
+  readonly mode: PresentationMode
+  readonly services = new ServiceRegistry()
+  readonly events: EventBus
+  #log: Logger
+  #config: Record<string, unknown>
+  #environments?: Readonly<Record<string, EnvironmentSpec>>
+  #plugins: PluginDefinition[] = []
+  #state: 'idle' | 'starting' | 'started' | 'disposed' = 'idle'
+  #starting?: Promise<StartReport>
+  #disposing?: Promise<void>
+  #report?: StartReport
+
+  constructor(options: KernelOptions) {
+    this.mode = options.mode
+    this.#config = options.config ?? {}
+    this.#environments = options.environments && Object.freeze({ ...options.environments })
+    this.#log = options.log ?? console
+    this.events = options.events ?? createEventBus((error, event) => {
+      this.#log.error(`[presmium] handler for "${event.type}" threw`, error)
+    })
+  }
+
+  register(plugin: PluginDefinition): void {
+    if (this.#state !== 'idle') throw new Error(`cannot register ${plugin.manifest.id}: kernel already started`)
+    if (this.#plugins.some(p => p.manifest.id === plugin.manifest.id)) {
+      throw new Error(`plugin ${plugin.manifest.id} is already registered`)
+    }
+    this.#plugins.push(plugin)
+  }
+
+  provide<T>(token: ServiceToken<T>, implementation: T): void {
+    this.services.provide(token, implementation)
+  }
+
+  getService<T>(token: ServiceToken<T>): T | undefined {
+    return this.services.tryGet(token)
+  }
+
+  report(): StartReport | undefined {
+    return this.#report
+  }
+
+  start(): Promise<StartReport> {
+    if (this.#state !== 'idle') return Promise.reject(new Error('kernel already started'))
+    this.#state = 'starting'
+    return this.#starting = Promise.resolve().then(() => this.#start())
+  }
+
+  async #start(): Promise<StartReport> {
+    const plan = this.services.plan(this.#plugins.map(p => p.manifest), this.version)
+    const reports = new Map<string, PluginReport>()
+    for (const [id, reason] of plan.excluded) reports.set(id, this.#disable(id, reason))
+
+    const order: string[] = []
+    for (const id of plan.order) {
+      const plugin = this.#plugins.find(p => p.manifest.id === id)!
+      const unavailable = (plugin.manifest.requires ?? []).filter(r => !this.services.has(r.token))
+      const missing = unavailable.map(r => r.token.id)
+      if (unavailable.some(r => !r.optional)) {
+        const required = unavailable.filter(r => !r.optional).map(r => r.token.id)
+        reports.set(id, this.#disable(id, `missing required services: ${required.join(', ')}`, missing))
+        continue
+      }
+      order.push(id)
+      reports.set(id, await this.#setup(plugin, missing))
+    }
+
+    this.#report = { order, plugins: this.#plugins.map(p => ({ ...reports.get(p.manifest.id)!, ...p.manifest.name ? { name: p.manifest.name } : {} })), cycles: plan.cycles }
+    if (this.#state !== 'disposed') this.#state = 'started'
+    return this.#report
+  }
+
+  dispose(): Promise<void> {
+    if (this.#disposing) return this.#disposing
+    this.#state = 'disposed'
+    return this.#disposing = this.#dispose()
+  }
+
+  async #dispose(): Promise<void> {
+    await this.#starting?.catch(() => undefined)
+    const running = new Set(
+      this.#report?.plugins.filter(r => r.status === 'started' || r.status === 'degraded').map(r => r.id),
+    )
+    for (const id of [...(this.#report?.order ?? [])].reverse()) {
+      if (!running.has(id)) continue
+      const plugin = this.#plugins.find(p => p.manifest.id === id)!
+      await this.#disposePlugin(plugin)
+    }
+  }
+
+  async #setup(plugin: PluginDefinition, missing: string[]): Promise<PluginReport> {
+    const { id, provides = [] } = plugin.manifest
+    try {
+      await plugin.setup(this.#context(plugin))
+      const unprovided = provides.filter(t => this.services.owner(t) !== id).map(t => t.id)
+      if (unprovided.length > 0) throw new Error(`declared but did not provide: ${unprovided.join(', ')}`)
+    } catch (error) {
+      await this.#disposePlugin(plugin)
+      const reason = errorMessage(error)
+      this.#log.error(`[presmium] ${id} failed to start`, error)
+      this.#emit({ type: 'kernel.plugin.failed', payload: { id, error: reason } })
+      return { id, status: 'failed', reason }
+    }
+    if (missing.length > 0) {
+      this.#log.warn(`[presmium] ${id} started without optional services: ${missing.join(', ')}`)
+      this.#emit({ type: 'kernel.plugin.degraded', payload: { id, missing } })
+      return { id, status: 'degraded', reason: `optional services unavailable: ${missing.join(', ')}`, missing }
+    }
+    this.#emit({ type: 'kernel.plugin.started', payload: { id } })
+    return { id, status: 'started' }
+  }
+
+  async #disposePlugin(plugin: PluginDefinition): Promise<void> {
+    try {
+      await plugin.dispose?.()
+    } catch (error) {
+      this.#log.error(`[presmium] ${plugin.manifest.id} dispose failed`, error)
+    } finally {
+      this.services.revoke(plugin.manifest.id)
+    }
+  }
+
+  #disable(id: string, reason: string, missing?: string[]): PluginReport {
+    this.#log.warn(`[presmium] ${id} disabled: ${reason}`)
+    this.#emit({ type: 'kernel.plugin.disabled', payload: { id, reason } })
+    return missing ? { id, status: 'disabled', reason, missing } : { id, status: 'disabled', reason }
+  }
+
+  #emit(event: KernelEvent): void {
+    this.events.emit(event)
+  }
+
+  #context(plugin: PluginDefinition): PluginContext {
+    const { id, provides = [], requires = [] } = plugin.manifest
+    const declared = new Set([...requires.map(r => r.token.id), ...provides.map(t => t.id)])
+    const assertDeclared = (token: ServiceToken<unknown>) => {
+      if (!declared.has(token.id)) throw new Error(`${id} did not declare service ${token.id} in its manifest`)
+    }
+    const config = this.#config[id]
+    return {
+      config: isRecord(config) ? { ...config } : {},
+      mode: this.mode,
+      provide: (token, implementation) => {
+        if (!provides.some(t => t.id === token.id)) {
+          throw new Error(`${id} provides ${token.id} without declaring it in manifest.provides`)
+        }
+        this.services.provide(token, implementation, id)
+      },
+      get: token => {
+        assertDeclared(token)
+        return this.services.get(token)
+      },
+      tryGet: token => {
+        assertDeclared(token)
+        return this.services.tryGet(token)
+      },
+      events: this.events,
+      log: prefixedLogger(this.#log, id),
+      ...this.#environments ? { environments: this.#environments } : {},
+    }
+  }
+}

package/src/keyboard.ts

@@ -0,0 +1,43 @@
+// Which key presses a page shortcut may take. Text entry, editors and open menus or dialogs keep every key. A control
+// the keyboard moved to keeps the keys it uses itself: Space presses a button or toggles a checkbox, and the arrows move
+// a slider, a select, a pane separator, the items of a toolbar or tab list, or scroll a focusable region. A click leaves the focus on the
+// clicked control; Space and the arrows then mean what they mean everywhere else on the page (play or pause, the next
+// step) instead of pressing that control again.
+
+const TEXT = 'textarea, [contenteditable]:not([contenteditable="false"]), input:not([type="button"], [type="checkbox"], [type="radio"], [type="range"], [type="reset"], [type="submit"], [type="color"], [type="file"], [type="image"])'
+const LAYER = '[role="dialog"], [role="alertdialog"], [role="menu"], [role="listbox"]'
+const PRESSABLE = 'button, a[href], summary, select, input, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="tab"], [role="option"], [role="treeitem"]'
+const NAVIGABLE = 'select, input[type="range"], [role="slider"], [role="spinbutton"], [role="tablist"], [role="toolbar"], [role="radiogroup"], [role="grid"], [role="tree"], [role="menubar"]'
+const NAVIGATION_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'PageUp', 'PageDown'])
+
+const sources = new WeakMap<Document, { pointer: boolean, byPointer: WeakSet<Element> }>()
+
+/** Starts noting, in `document`, which elements took the focus from a pointer press. Call it before the first click. */
+export function watchFocusSource(document: Document | undefined = globalThis.document): void {
+  if (!document || sources.has(document)) return
+  const source = { pointer: false, byPointer: new WeakSet<Element>() }
+  sources.set(document, source)
+  document.addEventListener('pointerdown', () => { source.pointer = true }, true)
+  document.addEventListener('keydown', () => { source.pointer = false }, true)
+  document.addEventListener('focusin', event => {
+    const target = event.composedPath()[0]
+    if (!(target instanceof Element)) return
+    if (source.pointer) source.byPointer.add(target)
+    else source.byPointer.delete(target)
+  }, true)
+}
+
+/** Whether a key press belongs to the element it was pressed on, so that a page shortcut leaves it alone. */
+export function keyBelongsToTarget(event: KeyboardEvent): boolean {
+  if (event.isComposing || event.keyCode === 229) return true
+  const target = event.composedPath?.()[0] ?? event.target
+  if (!(target instanceof Element)) return false
+  if ((target as HTMLElement).isContentEditable || target.closest(TEXT) || target.closest(LAYER)) return true
+  if (event.key !== ' ' && !NAVIGATION_KEYS.has(event.key)) return false
+  // Resize handles keep their keys after pointer focus too; resizing must never
+  // navigate a teaching step or start its playback.
+  if (target.closest('[role="separator"]')) return true
+  if (sources.get(target.ownerDocument)?.byPointer.has(target)) return false
+  const region = (target as HTMLElement).tabIndex >= 0 && !target.matches(`${PRESSABLE}, ${NAVIGABLE}`)
+  return region || Boolean(target.closest(event.key === ' ' ? PRESSABLE : NAVIGABLE))
+}

package/src/locale.ts

@@ -0,0 +1,13 @@
+import { DEFAULT_LANG } from './contracts/locale.ts'
+import type { Locale } from './contracts/locale.ts'
+
+export function localeOf(lang: string | null | undefined): Locale | undefined {
+  const tag = lang?.trim().toLowerCase() ?? ''
+  if (tag === 'zh' || tag.startsWith('zh-')) return 'zh-CN'
+  if (tag === 'en' || tag.startsWith('en-')) return 'en'
+  return undefined
+}
+
+export function deckLocale(lang?: string): Locale {
+  return localeOf(lang || DEFAULT_LANG) ?? 'en'
+}