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

package/src/fingerprint.ts

@@ -1,4 +1,4 @@
-export function normalizeWhitespace(text: string): string {
+function normalizeWhitespace(text: string): string {
   const lines = text
     .replace(/\r\n?/g, '\n')
     .split('\n')

package/src/follow.ts

@@ -1,37 +1,33 @@
-import type { IRBlock, IRSection } from './ir.ts'
+import type { IRSection } from './ir.ts'
+import { stepTrail, trailStep } from './step-keys.ts'
+import type { StepKeys } from './step-keys.ts'
 
-export type StepKeys = string[][]
-
-export function stepKeys(section: Pick<IRSection, 'blocks' | 'steps'>, renderer?: string): StepKeys {
-  const keys: StepKeys = Array.from({ length: section.steps + 1 }, () => [])
-  const add = (step: number, key: string) => step > 0 && keys[step]?.push(key)
-  let left = false
-  const visit = (blocks: readonly IRBlock[], prefix: string) => {
-    for (const block of blocks) {
-      if (renderer !== undefined && block.only && !block.only.includes(renderer)) {
-        left = true
-        continue
-      }
-      const id = prefix + block.id
-      if (block.role === 'visual') {
-        for (let k = 0; k <= (block.span ?? 0); k++) add(block.at + k, k === 0 ? id : `${id}+${k}`)
-        if (block.until !== undefined) add(block.until, `${id}-`)
-      }
-      if (block.node.type === 'component' && block.node.children) visit(block.node.children, `${id}/`)
-    }
-  }
-  visit(section.blocks, '')
-  return left ? keys.filter((step, i) => i === 0 || step.length > 0) : keys
+/** The presenter's position by ID, so learners with another version of the document reach the same place. */
+export interface FollowAnchor {
+  section?: string
+  trail?: string[]
+  back?: string
 }
 
-export function stepTrail(keys: StepKeys, step: number): string[] {
-  return keys.slice(1, step + 1).flat()
+const LEARNERS = 'student'
+
+/** For a section only some audiences have: the nearest earlier section that the other versions have too. */
+export function backSection(sections: readonly Pick<IRSection, 'id' | 'audience'>[], id: string): string | undefined {
+  const at = sections.findIndex(section => section.id === id)
+  const audience = sections[at]?.audience
+  if (!audience?.length) return undefined
+  const learners = !audience.includes(LEARNERS)
+  return sections.slice(0, at).findLast(section => !section.audience?.length || (learners && section.audience.includes(LEARNERS)))?.id
 }
 
-export function trailStep(keys: StepKeys, trail: readonly string[]): number {
-  const reached = new Set(trail)
-  for (let step = keys.length - 1; step > 0; step--) {
-    if (keys[step]!.some(key => reached.has(key))) return step
+/** Where a learner goes in their own version of the document when following the presenter's position. */
+export function followedPlace(position: FollowAnchor & { step: number }, keysOf: (id: string) => StepKeys | undefined): { section: string, step: number } | undefined {
+  const { section, trail, back, step } = position
+  const keys = section === undefined ? undefined : keysOf(section)
+  if (keys) {
+    const other = trail !== undefined && stepTrail(keys, step).join('\n') !== trail.join('\n')
+    return { section: section!, step: other ? trailStep(keys, trail) : step }
   }
-  return 0
+  const before = back === undefined ? undefined : keysOf(back)
+  return before && { section: back!, step: before.length - 1 }
 }

package/src/git.ts

@@ -1,4 +1,4 @@
-export const GIT_SAFE_CONFIG: readonly string[] = ['core.hooksPath=/dev/null', 'core.fsmonitor=false', 'core.quotePath=false', 'commit.gpgSign=false', 'tag.gpgSign=false']
+const GIT_SAFE_CONFIG: readonly string[] = ['core.hooksPath=/dev/null', 'core.fsmonitor=false', 'core.quotePath=false', 'commit.gpgSign=false', 'tag.gpgSign=false']
 
 export function gitConfigArgs(): string[] {
   return GIT_SAFE_CONFIG.flatMap(entry => ['-c', entry])

package/src/index.ts

@@ -1,29 +1,82 @@
 export * from './contracts.ts'
+export { applyDocumentOperations } from './document-operations.ts'
+export { validateDocumentChange, DOCUMENT_CHANGE_JSON_SCHEMA } from './authoring.ts'
+export { allocateDocumentPage, createDocumentPage, documentPageDefaults, DOCUMENT_PAGE_DEFAULT_TIMING, duplicateDocumentPage, moveDocumentPage, pageContents, pageDeletion, pageDeletionImpact, removeDocumentPage, renameDocumentPage } from './document-pages.ts'
+export { documentOutline, documentPart, DocumentReadError } from './document-reads.ts'
+export { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange, resolveDocumentStepVoice } from './document-voices.ts'
+export { DOCUMENT_COLOR_NAMES, documentColorToken, documentColorValue } from './document-colors.ts'
+export type { DocumentColorKind, DocumentColorName } from './document-colors.ts'
+export { applyDocumentCommentAction, isDocumentTextLink, documentCommentTargets, validateDocumentCommentAnchor, DocumentCommentError } from './document-comments.ts'
+export { applyDocumentAuthoringAction } from './document-authoring-actions.ts'
+export { applyDocumentComponentAction, effectiveComponentParameters, createDocumentParameterChanges, documentComponentSection, DocumentComponentError } from './document-components.ts'
+export type { DocumentStepVoice, DocumentVoiceImpact, DocumentVoiceOptions, DocumentVoiceScope } from './document-voices.ts'
+export { prepareTranscriptionAdoption } from './transcription-adoption.ts'
+export { productionAssetIds, recordingStepIssue, recordingSourceRange } from './recording.ts'
 export * from './ir.ts'
-export { createAnchorResolverRegistry, parseAnchor } from './anchors.ts'
+export { createAnchorResolverRegistry, isRenderable, parseAnchor } from './anchors.ts'
 export type { ParsedAnchor } from './anchors.ts'
-export { docBlocks, irBlocks, nodeMdast, withProp } from './blocks.ts'
+export { diagnosticOf } from './diagnostics.ts'
+export { DOCUMENT_JSON_SCHEMA, validateDocument } from './document.ts'
+export { validateDocumentParameters, documentParameterAccess, documentParameterSchemaForAccess } from './parameters.ts'
+export type { DocumentParameterAccess, DocumentParameterIssue, DocumentParameterSchemaReference, DocumentParameterValidation } from './parameters.ts'
+export { docBlocks, irBlocks, nodeMdast } from './blocks.ts'
 export { CheckRegistry } from './checks.ts'
-export { errorMessage, isRecord } from './errors.ts'
+export { errorMessage, isRecord, PreviewPreparing } from './errors.ts'
 export { createEventBus } from './events.ts'
-export { CREDENTIAL_VARIABLE, failedRun, languageId } from './execution.ts'
-export { GIT_SAFE_CONFIG, gitConfigArgs, gitEnvironment } from './git.ts'
+export { CREDENTIAL_VARIABLE, environmentExecutor, failedRun, languageId } from './execution.ts'
+export { gitConfigArgs, gitEnvironment } from './git.ts'
 export { escapeHtml, htmlAttributes, mapHtmlUrls, URL_ATTRIBUTES } from './html.ts'
 export type { HtmlAttribute } from './html.ts'
 export { hostName, localRequestRefusal } from './requests.ts'
 export type { RequestHeaders } from './requests.ts'
-export { fingerprint, fnv1a64, normalizeWhitespace } from './fingerprint.ts'
-export { stepKeys, stepTrail, trailStep } from './follow.ts'
-export type { StepKeys } from './follow.ts'
+export { fingerprint, fnv1a64 } from './fingerprint.ts'
+export { applyDocumentCaptionTiming, captionSourceFingerprint, captionTimingProblem, stepCaptionText, narrationCaptionText, CAPTION_TIMING_MAX_SEGMENTS, DocumentCaptionTimingError } from './document-caption-timings.ts'
+export type { DocumentCaptionTimingAction } from './document-caption-timings.ts'
+export { backSection, followedPlace } from './follow.ts'
+export type { FollowAnchor } from './follow.ts'
 export { Kernel } from './kernel.ts'
 export type { KernelOptions } from './kernel.ts'
+export { deckLocale, localeOf } from './locale.ts'
 export { ANCHOR_LOCK_PATH, AnchorLock } from './lock.ts'
-export { prefixed } from './logging.ts'
-export { lowerMyst, roleMark } from './markdown.ts'
-export type { LinkedType, LoweredMarkdown, LowerOptions } from './markdown.ts'
+export { prefixedLogger } from './logging.ts'
+export { lowerMyst, roleMark } from './lower-myst.ts'
+export type { LinkedType, LoweredMarkdown, LowerOptions } from './lower-myst.ts'
+export { connectPreviewFrame, isPreviewActive, isPreviewEmbedded, previewAppearance, previewFrameAncestors, reportPreview } from './preview-frame.ts'
+export { keyBelongsToTarget, watchFocusSource } from './keyboard.ts'
+export type { PreviewFrame, PreviewPage, PreviewProblem, PreviewTextEdit, PreviewTextHandle } from './preview-frame.ts'
+export { previewEditBinding } from './preview-edit.ts'
+export { pageEditCapability, pinPageSource, renamePageSource, movePageSource, removePageSource, pageRemovalTargets, pageIncomingReferences, writePage } from './page-source.ts'
+export type { PageEditCapability, PageEditReason, PageRemoval } from './page-source.ts'
+export { propText, withProp } from './props.ts'
 export { publishedUrl } from './published.ts'
 export type { PublishedUrlOptions } from './published.ts'
-export { blockState, blockText, blockVisible, chapters, isChapterTitle, mdastText, narrationAt, sectionNarration, tokenize } from './reading.ts'
+export { blockState, blockText, blockVisible, blockStepState, chapters, isChapterTitle, mdastText, narrationAt, sectionNarration, tokenize } from './reading.ts'
 export type { Chapter } from './reading.ts'
-export { HOST_OWNER, kernelIncompatibility, ServiceRegistry } from './services.ts'
+export { slideChapters, slideShape } from './slides.ts'
+export { compactSteps, viewFor } from './views.ts'
+export type { SlideShape } from './slides.ts'
+export { jsonResponse, problemResponse, sseResponse } from './responses.ts'
+export { kernelIncompatibility, ServiceRegistry } from './services.ts'
 export type { StartPlan } from './services.ts'
+export { remapWords, splitWords } from './speech-words.ts'
+export type { TextWord, WordSpan, WrittenWord } from './speech-words.ts'
+export { stepKeys, stepTrail, trailStep } from './step-keys.ts'
+export type { StepKeys } from './step-keys.ts'
+export { parseDuration } from './durations.ts'
+export { stepStateAt } from './steps.ts'
+export { ABSOLUTE_URL, NON_FILE_URL, urlSlug } from './urls.ts'
+export { isButton } from './lower-myst.ts'
+export { componentProps, findComponentRenderer, hasRendererExtension, WEB_RENDERER_PACKAGE, withPublishedAssets } from './renderer-components.ts'
+export { htmlAsText, isProseRun } from './run-outputs.ts'
+export { safeDecodeURIComponent } from './uri-decoding.ts'
+export { APPROVAL_KINDS, hasRole, isPresentingRole, LOCAL_AUTHOR } from './access.ts'
+export { pushStream } from './push-stream.ts'
+export type { PushStream, PushStreamOptions } from './push-stream.ts'
+export { aigcLabel, aigcString, speechEngineId } from './speech.ts'
+export { documentVoice, resolvedVoice, speechVoice, stepVoiceReason, voiceOverrides, voiceTarget } from './voice.ts'
+export { isCjk } from './speech-words.ts'
+export { componentCode } from './component-code.ts'
+export { jupyterKernelLanguage } from './jupyter-kernel.ts'
+
+export { createPreviewEvents } from './preview-events.ts'
+export type { PreviewEvents } from './preview-events.ts'

package/src/ir.ts

@@ -26,10 +26,21 @@ 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
@@ -46,6 +57,9 @@ export interface IRDocument {
   }
   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 {
@@ -56,6 +70,11 @@ export interface IRSection {
   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[]
@@ -74,6 +93,8 @@ export interface IRBlock {
   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
@@ -82,6 +103,8 @@ 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 {
@@ -129,6 +152,8 @@ export interface CodeNode {
   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 {
@@ -137,9 +162,13 @@ export interface ComponentNode {
   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'
@@ -233,24 +262,32 @@ export interface RenderContext {
   outDir: string
   workDir: string
   config: Record<string, unknown>
-  extensions: RendererExtension[]
+  extensions: BoundRendererExtension[]
   plugins: string[]
   pluginDirs: Record<string, string>
   lang?: string
   renderers: RendererId[]
   base: string
-  vitePlugins: unknown[]
+  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
@@ -276,8 +313,7 @@ export interface RenderDevServer {
 export interface Renderer {
   id: RendererId
   site?: boolean
-  support(node: IRNode, extensions: RendererExtension[]): Support
-  prepare?(doc: IRDocument, ctx: RenderContext): Promise<void>
+  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>
@@ -287,10 +323,12 @@ export interface Renderer {
 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 {
@@ -303,6 +341,17 @@ export interface SiteSpec {
 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>
 }
 
@@ -312,7 +361,7 @@ export interface RendererContribution {
   components?: Record<string, ComponentRenderer>
 }
 
-export interface RendererExtension {
+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

@@ -11,9 +11,9 @@ import type {
   ServiceToken,
   StartReport,
 } from './contracts.ts'
-import { errorMessage } from './errors.ts'
+import { errorMessage, isRecord } from './errors.ts'
 import { createEventBus } from './events.ts'
-import { prefixed } from './logging.ts'
+import { prefixedLogger } from './logging.ts'
 import { ServiceRegistry } from './services.ts'
 
 export interface KernelOptions {
@@ -34,6 +34,8 @@ export class Kernel {
   #environments?: Readonly<Record<string, EnvironmentSpec>>
   #plugins: PluginDefinition[] = []
   #state: 'idle' | 'starting' | 'started' | 'disposed' = 'idle'
+  #starting?: Promise<StartReport>
+  #disposing?: Promise<void>
   #report?: StartReport
 
   constructor(options: KernelOptions) {
@@ -54,8 +56,8 @@ export class Kernel {
     this.#plugins.push(plugin)
   }
 
-  provide<T>(token: ServiceToken<T>, impl: T): void {
-    this.services.provide(token, impl)
+  provide<T>(token: ServiceToken<T>, implementation: T): void {
+    this.services.provide(token, implementation)
   }
 
   getService<T>(token: ServiceToken<T>): T | undefined {
@@ -66,9 +68,13 @@ export class Kernel {
     return this.#report
   }
 
-  async start(): Promise<StartReport> {
-    if (this.#state !== 'idle') throw new Error('kernel already started')
+  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))
@@ -87,26 +93,26 @@ export class Kernel {
       reports.set(id, await this.#setup(plugin, missing))
     }
 
-    this.#report = { order, plugins: this.#plugins.map(p => reports.get(p.manifest.id)!), cycles: plan.cycles }
-    this.#state = 'started'
+    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
   }
 
-  async dispose(): Promise<void> {
-    if (this.#state === 'disposed') return
+  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)!
-      try {
-        await plugin.dispose?.()
-      } catch (error) {
-        this.#log.error(`[presmium] ${id} dispose failed`, error)
-      }
-      this.services.revoke(id)
+      await this.#disposePlugin(plugin)
     }
   }
 
@@ -117,7 +123,7 @@ export class Kernel {
       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) {
-      this.services.revoke(id)
+      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 } })
@@ -132,6 +138,16 @@ export class Kernel {
     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 } })
@@ -148,14 +164,15 @@ export class Kernel {
     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: pluginConfig(this.#config[id]),
+      config: isRecord(config) ? { ...config } : {},
       mode: this.mode,
-      provide: (token, impl) => {
+      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, impl, id)
+        this.services.provide(token, implementation, id)
       },
       get: token => {
         assertDeclared(token)
@@ -166,12 +183,8 @@ export class Kernel {
         return this.services.tryGet(token)
       },
       events: this.events,
-      log: prefixed(this.#log, id),
+      log: prefixedLogger(this.#log, id),
       ...this.#environments ? { environments: this.#environments } : {},
     }
   }
 }
-
-function pluginConfig(value: unknown): Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value) ? { ...value } : {}
-}

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'
+}

package/src/lock.ts

@@ -1,6 +1,6 @@
-import { isRenderable } from './contracts.ts'
+import { isRenderable } from './anchors.ts'
 import type { AnchorLockFile, RecordedAnchor, Resolution } from './contracts.ts'
-import { errorMessage } from './errors.ts'
+import { errorMessage, isRecord } from './errors.ts'
 
 export const ANCHOR_LOCK_PATH = '.presmium/anchors.lock.json'
 
@@ -67,11 +67,11 @@ export class AnchorLock {
 }
 
 function validate(data: unknown): AnchorLockFile {
-  if (!isObject(data) || data.version !== 1 || !isObject(data.anchors)) {
+  if (!isRecord(data) || data.version !== 1 || !isRecord(data.anchors)) {
     throw new Error('invalid anchor lock: expected { "version": 1, "anchors": { ... } }')
   }
   for (const [anchor, record] of Object.entries(data.anchors)) {
-    const valid = isObject(record)
+    const valid = isRecord(record)
       && typeof record.fingerprint === 'string' && record.fingerprint !== ''
       && typeof record.file === 'string'
       && Number.isInteger(record.startLine) && (record.startLine as number) >= 1
@@ -79,7 +79,3 @@ function validate(data: unknown): AnchorLockFile {
   }
   return data as unknown as AnchorLockFile
 }
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}

package/src/logging.ts

@@ -1,6 +1,6 @@
 import type { Logger } from './contracts.ts'
 
-export function prefixed(log: Logger, id: string): Logger {
+export function prefixedLogger(log: Logger, id: string): Logger {
   const tag = `[${id}]`
   return {
     debug: (...args) => log.debug(tag, ...args),

package/src/{markdown.ts → lower-myst.ts}

@@ -198,7 +198,8 @@ function cardsAs(options: LowerOptions): 'element' | 'headings' {
   return options.cards ?? (options.iframes === 'element' ? 'element' : 'headings')
 }
 
-function isButton(node: MdastNode): boolean {
+/** Whether a MyST node has the class `button`, which renders a link or span as a button. */
+export function isButton(node: MdastNode): boolean {
   return typeof node.class === 'string' && node.class.split(/\s+/).includes('button')
 }
 

package/src/node/assets.ts

@@ -0,0 +1,23 @@
+import { cpSync, existsSync, mkdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import type { LocalAsset } from '../ir.ts'
+
+/** Production assets are local to one document; hidden, remote and shared paths are not admitted. */
+export function productionAssetFile(deckDir: string, location: string): string | undefined {
+  if (!location || /^(?:[a-z][a-z\d+.-]*:|\/)/i.test(location) || /[\\\0?#]/.test(location)) return undefined
+  let decoded: string
+  try { decoded = decodeURIComponent(location) } catch { return undefined }
+  if (/[\\\0?#]/.test(decoded)) return undefined
+  const parts = decoded.split('/')
+  if (parts.some(part => !part || part.startsWith('.') || part === 'node_modules' || part === 'dist' || part.includes(':'))) return undefined
+  return resolve(deckDir, ...parts)
+}
+
+export function copyPublished(found: LocalAsset, dir: string): string {
+  const target = join(dir, found.name)
+  if (!existsSync(target)) {
+    mkdirSync(dir, { recursive: true })
+    cpSync(found.file, target, { recursive: true })
+  }
+  return target
+}