@lincyaw/kernel 1.0.0-rc.0 → 1.0.0-rc.1

package/src/contracts/document-voice.ts

@@ -0,0 +1,44 @@
+import type { CanonicalSource } from '../ir.ts'
+import type { Finding } from './checks.ts'
+import type { Member } from './server.ts'
+import type { SpeechEngineInfo } from './speech.ts'
+import type { VoiceCatalogAnswer, VoiceoverCancellation } from './voice.ts'
+import type { DocumentVoiceTasks, VoiceoverJobQuery, VoiceoverStart, VoicePreviewStart } from './voiceover-execution.ts'
+
+export interface DocumentVoiceCapabilities {
+  document: string
+  source: CanonicalSource
+  /** Configuration discovery does not prove provider authentication or synthesis success. */
+  verification: 'configuration-only'
+  status: 'configured' | 'unavailable' | 'unknown'
+  reason?: 'not-configured' | 'services-unavailable'
+  voiceover: boolean
+  preview: boolean
+  engines: SpeechEngineInfo[]
+  defaultEngine?: string
+  actions: { status: boolean, list: true, get: true, start: boolean, cancel: true, quotePreview: boolean, preview: boolean, readPreview: true }
+  tasks: { idempotency: 'process', limits: { intents: number, recentJobs: number, concurrent: number, quotes: number, quoteLifetimeMs: number, previewBytes: number, previewResources: number, retainedPreviewBytes: number } }
+  findings?: Finding[]
+}
+export interface DocumentVoiceCatalogQuery { source?: CanonicalSource, engine?: string, lang?: string }
+export interface DocumentVoiceCatalogAnswer extends VoiceCatalogAnswer { document: string, source: CanonicalSource, findings?: Finding[] }
+
+/** Shared voice discovery and explicitly authorized tasks; discovery never compiles or synthesizes. */
+export interface DocumentVoiceAuthoring extends DocumentVoiceTasks {
+  capabilities(document: string, member: Member, signal?: AbortSignal): Promise<DocumentVoiceCapabilities>
+  catalog(document: string, query: DocumentVoiceCatalogQuery, member: Member, signal?: AbortSignal): Promise<DocumentVoiceCatalogAnswer>
+  /** Checks a start or preview with the same path as the action, without synthesizing, so an agent asks only for one that would run. */
+  checkStart(document: string, request: VoiceoverStart, member: Member, signal?: AbortSignal): Promise<void>
+  checkPreview(document: string, request: VoicePreviewStart, member: Member, signal?: AbortSignal): Promise<void>
+  /** Undefined when there is something to cancel; otherwise the unchanged state that cancel would report. */
+  checkCancel(document: string, query: VoiceoverJobQuery, member: Member): Promise<VoiceoverCancellation | undefined>
+}
+
+export const DOCUMENT_VOICE_CATALOG_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  properties: {
+    source: { type: 'object', additionalProperties: false, properties: { documentId: { type: 'string', minLength: 1, maxLength: 200 }, version: { type: 'string', pattern: '^[a-f\\d]{20}$' }, fingerprint: { type: 'string', pattern: '^[a-f\\d]{16}$' } }, required: ['documentId', 'version', 'fingerprint'] },
+    engine: { type: 'string', minLength: 1, maxLength: 200 },
+    lang: { type: 'string', minLength: 1, maxLength: 100 },
+  },
+} as const

package/src/contracts/document.ts

@@ -0,0 +1,240 @@
+import type { ExecuteConfig } from './execution.ts'
+import type { SpeechVoice } from './speech.ts'
+
+export const DOCUMENT_SCHEMA_VERSION = 1 as const
+export const DOCUMENT_ENTRY = 'lecture.json'
+export const ASSET_TITLE_MAX_LENGTH = 200
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject
+export interface JsonObject { [key: string]: JsonValue }
+export type JsonSchema = JsonObject | boolean
+export type DocumentId = string
+export type SectionId = string
+export type BlockId = string
+export type StepId = string
+export type NarrationId = string
+export type AssetId = string
+export type DefinitionId = string
+export type ClipId = string
+
+export interface DocumentMetadata {
+  title: string
+  lang: string
+  description?: string
+  tags?: string[]
+  plugins?: string[]
+  presmium?: Record<string, JsonObject>
+  renderers?: Record<string, JsonObject>
+  execute?: ExecuteConfig
+  checks?: JsonObject
+  translations?: Record<string, string>
+  translationOf?: { entry: string, digest: string }
+}
+
+/** Canonical authoring data. Runtime positions, resolved assets and playback plans are derived. */
+export interface TeachingDocument {
+  schemaVersion: typeof DOCUMENT_SCHEMA_VERSION
+  id: DocumentId
+  metadata: DocumentMetadata
+  sectionOrder: SectionId[]
+  sections: Record<SectionId, Section>
+  blocks: Record<BlockId, DocumentBlock>
+  steps: Record<StepId, Step>
+  narrations: Record<NarrationId, Narration>
+  assets: Record<AssetId, Asset>
+  definitions: Record<DefinitionId, Definition>
+  production: Production
+  comments?: Record<string, DocumentThread>
+}
+
+export interface Layout {
+  type: 'stack' | 'columns' | 'canvas' | 'scrolly'
+  properties?: JsonObject
+  renderers?: Record<string, JsonObject>
+}
+export interface Section {
+  id: SectionId
+  title: string
+  level?: 1 | 2 | 3 | 4 | 5 | 6
+  children: BlockId[]
+  stepOrder: StepId[]
+  layout: Layout
+  audience?: string[]
+  config?: Record<string, JsonObject>
+}
+
+export type TextAlignment = 'left' | 'center' | 'right' | 'justify'
+export interface TextStyle { alignment?: TextAlignment, color?: string, background?: string }
+export type TextMark =
+  | { type: 'bold' | 'italic' | 'underline' | 'strike' | 'code' }
+  | { type: 'color' | 'background', value: string }
+export type InlineNode =
+  | { type: 'text', text: string, marks?: TextMark[] }
+  | { type: 'link', href: string, children: InlineNode[] }
+  | { type: 'math', value: string }
+  | { type: 'break' }
+  | InlineExtensionNode
+
+/** A registered extension retains its own versioned semantics and an explicit readable fallback. */
+export interface InlineExtensionNode { type: 'extension', kind: string, schemaVersion: number, data: JsonObject, fallback: string }
+export interface RichTextExtensionNode { id: string, type: 'extension', kind: string, schemaVersion: number, data: JsonObject, fallback: RichTextNode[] }
+
+export interface ParagraphNode { id: string, type: 'paragraph', children: InlineNode[], style?: TextStyle }
+export interface HeadingNode { id: string, type: 'heading', level: 1 | 2 | 3 | 4 | 5 | 6, children: InlineNode[], style?: TextStyle }
+export interface ListItemNode { id: string, type: 'listItem', children: RichTextNode[], checked?: boolean }
+export interface ListNode { id: string, type: 'list', ordered: boolean, start?: number, children: ListItemNode[] }
+export interface QuoteNode { id: string, type: 'blockquote', children: RichTextNode[] }
+export interface CodeTextNode { id: string, type: 'code', language: string, value: string }
+export interface MathTextNode { id: string, type: 'math', value: string }
+export interface TableCellNode { id: string, type: 'tableCell', children: InlineNode[], style?: TextStyle, colspan?: number, rowspan?: number }
+export interface TableRowNode { id: string, type: 'tableRow', children: TableCellNode[] }
+export interface TableNode { id: string, type: 'table', children: TableRowNode[], headerRows?: number, headerColumns?: number, columnWidths?: number[] }
+export type RichTextNode = ParagraphNode | HeadingNode | ListNode | QuoteNode | CodeTextNode | MathTextNode | TableNode | RichTextExtensionNode
+
+export interface BlockScope { only?: string[], audience?: string[] }
+export interface TextBlock extends BlockScope { id: BlockId, type: 'text', content: RichTextNode[], reveal?: { type: 'items', order: string[] } }
+export interface ContainerProperties { title?: string, columnWidths?: number[], tabTitles?: string[] }
+export interface ContainerBlock extends BlockScope { id: BlockId, type: 'container', layout: 'stack' | 'columns' | 'tabs', children: BlockId[], properties: ContainerProperties }
+/** An image without an asset is an authored placeholder, not an asset with an empty location. */
+export interface ImageBlock extends BlockScope { id: BlockId, type: 'image', assetId?: AssetId, alt: string, caption?: InlineNode[], width?: number, alignment?: TextAlignment }
+export interface CodeReference { anchor: string, pin?: string, repo?: string, highlightRegions?: Record<StepId, string> }
+export interface CodeExecution { args?: Record<string, string>, stdin?: string, timeoutMs?: number, executor?: string, when: 'compile' | 'live' | 'both', session?: string }
+export interface CodeVariantSource { id: string, title: string, value?: string, origin?: Omit<CodeReference, 'highlightRegions'> }
+export interface CodeBlock extends BlockScope {
+  id: BlockId
+  type: 'code'
+  language: string
+  value?: string
+  origin?: CodeReference
+  title?: string
+  execution?: CodeExecution
+  highlight?: Record<StepId, number[]>
+  variants?: CodeVariantSource[]
+  echo?: boolean
+}
+export interface ComponentBlock extends BlockScope { id: BlockId, type: 'component', definitionId: DefinitionId, parameters: JsonObject, children?: BlockId[] }
+export type DocumentBlock = TextBlock | ContainerBlock | ImageBlock | CodeBlock | ComponentBlock
+
+/** State is independent from ordering and production timing. Omitted blocks are invisible. */
+export interface Step {
+  id: StepId
+  sectionId: SectionId
+  title?: string
+  visuals: VisualState[]
+  narrationIds: NarrationId[]
+  inherits?: StepId
+}
+export interface VisualState { blockId: BlockId, visible: boolean, state?: string, parameters?: JsonObject }
+export type NarrationNode =
+  | { type: 'text', text: string }
+  | { type: 'pronunciation', display: string, spoken: string }
+  | { id: string, type: 'cue', action: string, target?: { blockId: BlockId, element?: string }, parameters?: JsonObject }
+export interface Narration {
+  id: NarrationId
+  content: NarrationNode[]
+  /** Attribution of an explicit adoption; never a second caption or spoken-text source. */
+  provenance?: { type: 'transcription', transcriptionId: string, revision: string, assetId: AssetId, audioSha256: string, segmentIds: string[] }
+}
+
+export interface Asset { id: AssetId, kind: 'image' | 'audio' | 'video' | 'file', location: string, title?: string, fingerprint?: string, mediaType?: string }
+export type ImplementationRef =
+  | { type: 'file', path: string, exportName?: string, fingerprint?: string }
+  | { type: 'module', specifier: string, exportName?: string }
+  | { type: 'plugin', plugin: string, name: string }
+export interface StateDescriptor {
+  id: string
+  title?: string
+  parameterSchema?: JsonSchema
+  /** A migration must retain numerical implementation bindings explicitly, never invent semantic names. */
+  legacyIndex?: number
+}
+export interface Definition {
+  id: DefinitionId
+  kind: string
+  schemaVersion: number
+  implementation: ImplementationRef
+  parameterSchema: JsonSchema
+  states: StateDescriptor[]
+  data?: JsonObject
+}
+
+export type VoiceSource = { type: 'none' } | { type: 'tts', voice: SpeechVoice } | { type: 'recording', assetId: AssetId, sourceRange?: TimeRange }
+export interface StepProduction {
+  narrationStart?: 'with-animation' | 'after-animation'
+  minimumHoldMs?: number
+  trailingPauseMs?: number
+  voiceSource?: VoiceSource
+}
+export interface ProductionDefaults extends StepProduction {}
+export interface TimeRange { startMs: number, endMs: number }
+/** Explicit author times; offsets partition the original ordered step narration display in UTF16. */
+export interface CaptionTiming {
+  narrationIds: NarrationId[]
+  sourceFingerprint: string
+  playbackFingerprint: string
+  durationMs: number
+  segments: { id: string, from: number, to: number, startMs: number, endMs: number }[]
+}
+export interface MediaClip {
+  id: ClipId
+  assetId: AssetId
+  sourceRange: TimeRange
+  attachment: { stepId: StepId, offsetMs: number }
+  /** Output gain, from zero to one; muting does not replace this value. */
+  volume: number
+  muted?: boolean
+}
+export interface Production {
+  defaults: ProductionDefaults
+  sectionOverrides?: Record<SectionId, StepProduction>
+  stepOverrides: Record<StepId, StepProduction>
+  /** Migrated narration defaults: after page settings, before an explicit step override; shared narrations retain this source. */
+  narrationOverrides?: Record<NarrationId, { narrationStart: 'with-animation' | 'after-animation' }>
+  /** Cue placement is authored in narration; its delay is owned only here. */
+  cueTimings?: Record<string, { pauseMs: number }>
+  /** Stale mappings remain inspectable but never retime audio or replace changed narration. */
+  captionTimings?: Record<StepId, CaptionTiming>
+  mediaClips: MediaClip[]
+}
+
+/** A stable rich-text/code ID, or `page:${sectionId}` reserved for an existing section title. */
+export interface DocumentTextPoint { blockId: string, offset: number }
+export interface DocumentComment {
+  id: string
+  type: 'comment'
+  userId: string
+  createdAt: string
+  updatedAt: string
+  deletedAt?: string
+  content?: RichTextNode[]
+  metadata?: JsonObject
+  reactions: { emoji: string, createdAt: string, userIds: string[] }[]
+}
+export interface DocumentThread {
+  id: string
+  type: 'thread'
+  createdAt: string
+  updatedAt: string
+  resolved: boolean
+  resolvedUpdatedAt?: string
+  resolvedBy?: string
+  metadata?: JsonObject
+  deletedAt?: string
+  anchor?: { from: DocumentTextPoint, to: DocumentTextPoint }
+  comments: DocumentComment[]
+}
+
+export interface DocumentIssue { path: string, code: string, message: string, severity: 'error' | 'warning' }
+export interface DocumentValidation { document?: TeachingDocument, issues: DocumentIssue[] }
+
+/** A source-document transaction. Its CAS version is unrelated to a compiled snapshot ID. */
+export type DocumentEditOperation =
+  | { type: 'insertBlock', sectionId: SectionId, parentId?: BlockId, index: number, block: DocumentBlock }
+  | { type: 'moveBlock', blockId: BlockId, sectionId: SectionId, parentId?: BlockId, index: number }
+  | { type: 'deleteBlock', blockId: BlockId }
+  | { type: 'updateText', blockId: BlockId, content: RichTextNode[] }
+  | { type: 'updateSection', sectionId: SectionId, title?: string, layout?: Layout }
+  | { type: 'setStepState', stepId: StepId, visuals: VisualState[], inherits?: StepId }
+  | { type: 'setNarration', narration: Narration, stepId?: StepId, index?: number }
+  | { type: 'setTiming', stepId?: StepId, sectionId?: SectionId, value: StepProduction }
+  | { type: 'replaceAsset', asset: Asset }

package/src/contracts/execution.ts

@@ -1,4 +1,4 @@
-import type { Logger, Unsubscribe } from '../contracts.ts'
+import type { Logger, Unsubscribe } from './plugin.ts'
 import { defineService } from './service.ts'
 
 export interface RunRequest {
@@ -10,6 +10,7 @@ export interface RunRequest {
   files?: Record<string, string>
   executor?: string
   session?: string
+  place?: { section: string, block: string }
 }
 
 export type RunOutput =
@@ -91,6 +92,8 @@ export interface EnvironmentSpec {
   kernel?: string
   languages?: string[]
   auth?: EnvironmentAuth
+  /** Operator-defined JupyterHub environment profile; images and resource limits stay on the Hub. */
+  profile?: string
   image?: string
   path?: string
   [option: string]: unknown
@@ -102,10 +105,6 @@ export interface ExecuteConfig {
   rerun?: 'environment'
 }
 
-export function environmentExecutor(name: string): string {
-  return `presmium.env.${name}`
-}
-
 export interface EnvironmentContext {
   deckDir: string
   workspaceRoot: string

package/src/contracts/locale.ts

@@ -0,0 +1,3 @@
+export type Locale = 'zh-CN' | 'en'
+
+export const DEFAULT_LANG = 'zh-CN'

package/src/contracts/offline.ts

@@ -0,0 +1,2 @@
+/** The requests a page sends the web form's service worker, with a MessageChannel port for the answer. */
+export const OFFLINE_REQUESTS = { runtimes: 'presmium:offline-runtimes', save: 'presmium:save-offline' } as const

package/src/contracts/plugin.ts

@@ -0,0 +1,183 @@
+import type { CanonicalSource, DirectiveSpec, IRDocument, IRPass, Renderer, RendererContribution, RoleSpec } from '../ir.ts'
+import type { AgentTool } from './agent.ts'
+import type { AnchorResolver, AnchorString } from './anchors.ts'
+import type { Check, CheckContext } from './checks.ts'
+import type { EnvironmentProvider, EnvironmentSpec, Executor } from './execution.ts'
+import type { NodeServiceContext, ServerContext, ServerContribution } from './server.ts'
+import type { Locale } from './locale.ts'
+import type { ServiceToken } from './service.ts'
+
+export const KERNEL_VERSION = '1.0.0'
+
+export type Capability = 'fs' | 'network' | 'exec' | 'git'
+
+export interface ServiceRequirement {
+  token: ServiceToken<unknown>
+  optional?: boolean
+}
+
+export interface PluginManifest {
+  id: string
+  /** The name readers and authors see (the startup report), in both interface languages; the id is never shown. */
+  name?: Record<Locale, string>
+  version: string
+  kernel: string
+  provides?: ServiceToken<unknown>[]
+  requires?: ServiceRequirement[]
+  capabilities?: Capability[]
+}
+
+export type PresentationMode = 'slides' | 'document'
+
+export interface Logger {
+  debug(...args: unknown[]): void
+  info(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+}
+
+export type Unsubscribe = () => void
+
+export interface DomainEvent<Type extends string = string, Payload = unknown> {
+  type: Type
+  payload: Payload
+}
+
+export interface EventBus {
+  emit(event: DomainEvent): void
+  on<E extends DomainEvent>(type: E['type'], handler: (event: E) => void): Unsubscribe
+}
+
+export interface PluginContext {
+  config: Record<string, unknown>
+  mode: PresentationMode
+  provide<T>(token: ServiceToken<T>, implementation: T): void
+  get<T>(token: ServiceToken<T>): T
+  tryGet<T>(token: ServiceToken<T>): T | undefined
+  events: EventBus
+  log: Logger
+  environments?: Readonly<Record<string, EnvironmentSpec>>
+}
+
+export interface PluginDefinition {
+  manifest: PluginManifest
+  /** Opt in only when dispose stops every resource and this definition can run setup again. */
+  restartable?: boolean
+  setup(ctx: PluginContext): void | Promise<void>
+  /** Also called after setup fails; releases resources acquired during partial initialization. */
+  dispose?(): void | Promise<void>
+}
+
+export type PluginStatus = 'started' | 'degraded' | 'disabled' | 'failed'
+
+export interface PluginReport {
+  id: string
+  name?: Record<Locale, string>
+  status: PluginStatus
+  reason?: string
+  missing?: string[]
+}
+
+export interface StartReport {
+  order: string[]
+  plugins: PluginReport[]
+  cycles: string[][]
+}
+
+export type KernelEvent =
+  | DomainEvent<'kernel.plugin.started', { id: string }>
+  | DomainEvent<'kernel.plugin.degraded', { id: string; missing: string[] }>
+  | DomainEvent<'kernel.plugin.disabled', { id: string; reason: string }>
+  | DomainEvent<'kernel.plugin.failed', { id: string; error: string }>
+
+/**
+ * A heavy output of a document that the plugin makes on request, as a job of the workspace service (the slides as a PDF,
+ * the lecture as a video): the job shows its progress and log, and keeps the files for the author and the AI.
+ */
+export interface Exporter {
+  /** Unique among the outputs of a document, renderers' ids included (e.g. `pdf`, `video`). */
+  id: string
+  /** What the author sees, by language (`zh-CN`, `en`). */
+  label: Record<string, string>
+  /** Whether the document can be exported so (e.g. it has the slides form); every document when left out. */
+  available?(doc: IRDocument, config: Record<string, unknown>): boolean
+  run(ctx: ExportContext): Promise<ExportOutput>
+}
+
+export interface ExportContext {
+  deckDir: string
+  workspaceRoot: string
+  /** The exact canonical source from which the requested compilation was derived. */
+  source?: CanonicalSource
+  /** The plugin's configuration in the document (`presmium.<plugin id>`). */
+  config: Record<string, unknown>
+  /** An empty directory, the job's own, for the files. */
+  outDir: string
+  /** Aborted when the author cancels the job: the exporter stops its processes and rejects. */
+  signal: AbortSignal
+  /** Where the job is: a phase, and how far through it. */
+  progress(phase: string, done?: number, total?: number): void
+  /** A line of the job's log (a tool's output, a step). */
+  log(line: string): void
+  /** What the one who asked for the export chose, as the exporter documents it (`presmium-export`'s `--with-clicks`). */
+  options: Record<string, unknown>
+  /**
+   * Builds the document with renderer `renderer` (at the root path, with `config` over the document's configuration of
+   * the renderer) and gives the directory of its output, the job's own: an exporter of the slides prints them from it.
+   */
+  build(renderer: string, config?: Record<string, unknown>): Promise<string>
+}
+
+export interface ExportOutput {
+  /** The files made, below `outDir`, the one to show first. */
+  files: string[]
+  /** The WebVTT captions of the first file (a video), by language, among `files`. */
+  captions?: Record<string, string>
+  warnings?: string[]
+}
+
+/**
+ * Files of an installed package that a plugin's browser code loads while it runs (Pyodide, the WASI runtimes): served
+ * below the document's site path at `<base><prefix><file>` and copied there into a built site.
+ */
+export interface RuntimeAssets {
+  name: string
+  /** The directory below the document's site path, e.g. `pyodide/`. */
+  prefix: string
+  /** The files that are served, with their content types. */
+  types: Readonly<Record<string, string>>
+  /** The files a build copies; default: all that are served. */
+  emitted?: readonly string[]
+  /** The path of a file on disk. */
+  source(file: string): string
+}
+
+export interface PresmiumNodePlugin {
+  id: string
+  version?: string
+  kernel?: string
+  resolvers?: AnchorResolver[]
+  checks?: Check[]
+  anchors?(ctx: CheckContext): AnchorString[] | Promise<AnchorString[]>
+  directives?: DirectiveSpec[]
+  passes?: IRPass[]
+  executors?: Executor[]
+  renderer?: Renderer
+  rendererExtensions?: Record<string, RendererContribution>
+  /** The files the plugin's browser code loads while it runs (a language runtime), for the document's configuration of the plugin. */
+  assets?(ctx: { deckDir: string, workspaceRoot: string, config: Record<string, unknown> }): RuntimeAssets[]
+  /**
+   * The virtual modules of the plugin's browser code whose content depends on the document (e.g. the list of its scene
+   * files), by id, with their source. The viewer app, prebuilt once for all documents, gets them from the document's own
+   * bundle, built with this source. Only their default export is read there.
+   */
+  documentModules?(ctx: { deckDir: string, workspaceRoot: string, config: Record<string, unknown> }): Record<string, string>
+  /** The heavy outputs the plugin makes on request, as jobs of the workspace service. */
+  exporters?: Exporter[]
+  services?(ctx: NodeServiceContext): [ServiceToken<unknown>, unknown][]
+  environments?: Record<string, EnvironmentProvider>
+  server?(ctx: ServerContext): ServerContribution | Promise<ServerContribution>
+  roles?: RoleSpec[]
+  tools?: AgentTool[]
+  operator?: boolean
+}

package/src/contracts/presenter-panels.ts

@@ -0,0 +1,17 @@
+import type { Unsubscribe } from './plugin.ts'
+import { defineService } from './service.ts'
+
+export interface PresenterPanel {
+  id: string
+  title: string
+  component: unknown
+  order?: number
+}
+
+export interface PresenterPanels {
+  register(panel: PresenterPanel): Unsubscribe
+  list(): PresenterPanel[]
+  subscribe(listener: () => void): Unsubscribe
+}
+
+export const PRESENTER_PANELS = defineService<PresenterPanels>('presmium.presenterPanels')