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

package/src/props.ts

@@ -0,0 +1,17 @@
+import { isRecord } from './errors.ts'
+
+/** Sets the value at a dotted path, copying the objects on the way. */
+export function withProp(props: Record<string, unknown>, path: string, value: unknown): Record<string, unknown> {
+  const [key = '', ...rest] = path.split('.')
+  if (rest.length === 0) return { ...props, [key]: value }
+  const inner = props[key]
+  return { ...props, [key]: withProp(isRecord(inner) ? inner : {}, rest.join('.'), value) }
+}
+
+/** Every string in a component's props, nested arrays and objects included. */
+export function propText(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.flatMap(propText)
+  if (value && typeof value === 'object') return Object.values(value).flatMap(propText)
+  return []
+}

package/src/published.ts

@@ -0,0 +1,11 @@
+import type { LocalAsset } from './ir.ts'
+
+export interface PublishedUrlOptions {
+  prefix?: string
+  directoryIndex?: string
+}
+
+export function publishedUrl(found: Pick<LocalAsset, 'name' | 'directory'>, url: string, options: PublishedUrlOptions = {}): string {
+  const index = found.directory ? options.directoryIndex ?? '/index.html' : ''
+  return `${options.prefix ?? ''}${encodeURIComponent(found.name)}${index}${/[?#].*$/s.exec(url)?.[0] ?? ''}`
+}

package/src/push-stream.ts

@@ -0,0 +1,67 @@
+export interface PushStream<T> extends AsyncIterable<T> {
+  end(): void
+}
+
+export interface PushStreamOptions {
+  signal?: AbortSignal
+  /** Keep only the newest value the reader has not taken, for streams that say "something changed". */
+  latestOnly?: boolean
+}
+
+/**
+ * An async iterable of the values a subscription pushes. `subscribe` runs at once (unless the signal has
+ * aborted) and returns its unsubscribe, which runs once when the stream ends: on `end()`, on the signal,
+ * or when the reader stops.
+ */
+export function pushStream<T>(subscribe: (push: (value: T) => void) => () => void, options: PushStreamOptions = {}): PushStream<T> {
+  const { signal } = options
+  const queue: T[] = []
+  let wake: (() => void) | undefined
+  let ended = false
+  let unsubscribe: (() => void) | undefined
+  const end = () => {
+    if (ended) return
+    ended = true
+    signal?.removeEventListener('abort', end)
+    try { unsubscribe?.() }
+    finally { wake?.() }
+  }
+  if (signal?.aborted) {
+    ended = true
+  } else {
+    unsubscribe = subscribe((value) => {
+      if (ended) return
+      if (options.latestOnly) queue.splice(0, queue.length, value)
+      else queue.push(value)
+      wake?.()
+    })
+    if (signal?.aborted) end()
+    else signal?.addEventListener('abort', end, { once: true })
+  }
+  return {
+    end,
+    [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+      const iterator = (async function* () {
+        try {
+          while (!ended) {
+            if (queue.length > 0) {
+              yield queue.shift()!
+              continue
+            }
+            await new Promise<void>(resolve => wake = resolve)
+            wake = undefined
+          }
+        } finally {
+          end()
+        }
+      })()
+      // Wake a pending next() before the generator queues return() or throw().
+      return {
+        [Symbol.asyncIterator]() { return this },
+        next: value => iterator.next(value),
+        return(value) { end(); return iterator.return(value) },
+        throw(error) { end(); return iterator.throw(error) },
+      }
+    },
+  }
+}

package/src/reading.ts

@@ -0,0 +1,96 @@
+import { irBlocks } from './blocks.ts'
+import type { IRBlock, IRDocument, IRSection, MdastNode } from './ir.ts'
+import { propText } from './props.ts'
+
+export interface Chapter {
+  title: string
+  sections: IRSection[]
+}
+
+function sectionDepth(doc: IRDocument): number {
+  return doc.sections.reduce((depth, section) => Math.max(depth, section.depth), 0)
+}
+
+function titles(depth: number, section: IRSection): boolean {
+  return section.depth === 0 || section.depth < depth
+}
+
+export function isChapterTitle(doc: IRDocument, section: IRSection): boolean {
+  return titles(sectionDepth(doc), section)
+}
+
+export function chapters(doc: IRDocument): Chapter[] {
+  const depth = sectionDepth(doc)
+  const result: Chapter[] = []
+  let previous: IRSection | undefined
+  for (const section of doc.sections) {
+    const current = result.at(-1)
+    if (!current || section.source.file !== previous?.source.file || titles(depth, section)) {
+      result.push({ title: section.title, sections: [section] })
+    } else {
+      current.sections.push(section)
+    }
+    previous = section
+  }
+  return result
+}
+
+export function blockVisible(block: IRBlock, step: number): boolean {
+  const state = blockStepState(block, step)
+  if (state) return state.visible
+  return step >= block.at && (block.until === undefined || step < block.until)
+}
+
+export function blockState(block: IRBlock, step: number): number {
+  const state = blockStepState(block, step)
+  if (state) return state.localStep
+  return Math.min(Math.max(step - block.at, 0), block.span ?? 0)
+}
+
+export function blockStepState(block: IRBlock, step: number): NonNullable<IRBlock['stepStates']>[number] | undefined {
+  const states = block.stepStates
+  if (!states?.length) return undefined
+  const index = step === Number.POSITIVE_INFINITY ? states.length - 1 : Number.isFinite(step) ? Math.max(0, Math.min(Math.trunc(step), states.length - 1)) : 0
+  return states[index]
+}
+
+export function narrationAt(section: IRSection, step: number): IRBlock[] {
+  return section.blocks.filter(block => block.role === 'narration' && block.at === step)
+}
+
+export function sectionNarration(section: IRSection): IRBlock[] {
+  return [...irBlocks(section.blocks)].filter(block => block.role === 'narration')
+}
+
+const BREAKS = new Set(['paragraph', 'heading', 'listItem', 'tableRow', 'tableCell', 'code', 'math', 'blockquote', 'break'])
+
+function htmlText(html: string): string {
+  return html.replace(/<(style|script)\b[\s\S]*?<\/\1\s*>/gi, ' ').replace(/<[^>]*>/g, ' ')
+}
+
+export function mdastText(node: MdastNode): string {
+  if (node.type === 'html' && typeof node.value === 'string') return htmlText(node.value)
+  if (typeof node.value === 'string' && !node.children) return node.value
+  const text = (node.children ?? []).map(mdastText).join('')
+  return BREAKS.has(node.type) ? `${text}\n` : text
+}
+
+export function blockText(block: IRBlock): string {
+  const { node } = block
+  switch (node.type) {
+    case 'markdown': return mdastText(node.mdast).trim()
+    case 'code': return [node.title, node.value, ...(node.outputs ?? []).map(o => o.stdout)].filter(Boolean).join('\n')
+    case 'component': return [...propText(node.props), ...(node.children ?? []).map(blockText)].join('\n')
+  }
+}
+
+export function tokenize(text: string): string[] {
+  const segmenter = new Intl.Segmenter('zh', { granularity: 'word' })
+  const words: string[] = []
+  for (const piece of text.split(/[\n\r\p{Z}\p{P}]+/u)) {
+    for (const part of segmenter.segment(piece)) {
+      if (part.isWordLike) words.push(part.segment)
+    }
+  }
+  return words
+}

package/src/recording.ts

@@ -0,0 +1,38 @@
+import type { Production, TeachingDocument, TimeRange, VoiceSource } from './contracts/document.ts'
+
+/** Resolve only against a real inspected duration; no source bytes or authored text are changed. */
+export function recordingSourceRange(source: Extract<VoiceSource, { type: 'recording' }>, durationMs: number): TimeRange | undefined {
+  const range = source.sourceRange ?? { startMs: 0, endMs: durationMs }
+  return Number.isFinite(durationMs) && durationMs > 0 && Number.isFinite(range.startMs) && Number.isFinite(range.endMs)
+    && range.startMs >= 0 && range.endMs > range.startMs && range.endMs <= durationMs ? { ...range } : undefined
+}
+
+/** Assets used by surviving steps; inherited recordings are resolved before collecting references. */
+export function productionAssetIds(production: Production | undefined, sections: readonly { id: string, stepIds?: readonly string[] }[]): string[] {
+  if (!production) return []
+  const ids = new Set(production.mediaClips.map(clip => clip.assetId))
+  for (const section of sections) for (const stepId of section.stepIds ?? []) {
+    const source = production.stepOverrides[stepId]?.voiceSource ?? production.sectionOverrides?.[section.id]?.voiceSource ?? production.defaults.voiceSource
+    if (source?.type === 'recording') ids.add(source.assetId)
+  }
+  return [...ids]
+}
+
+/** Whole-step recordings have no inferred word clock. This check does not change authored atoms. */
+export function recordingStepIssue(document: TeachingDocument, stepId: string): 'recording-cue-unsupported' | 'recording-start-conflict' | undefined {
+  const step = document.steps[stepId]
+  if (!step) return undefined
+  let text = false, mode: string | undefined
+  for (const id of step.narrationIds) {
+    const value = { ...document.production.defaults, ...document.production.sectionOverrides?.[step.sectionId], ...document.production.narrationOverrides?.[id], ...document.production.stepOverrides[stepId] }
+    const next = value.narrationStart ?? 'with-animation'
+    if (mode !== undefined && mode !== next) return 'recording-start-conflict'
+    mode = next
+    for (const node of document.narrations[id]!.content) {
+      if (node.type === 'cue') {
+        const action = node.action.trim().split(/\s/)[0]
+        if (text || action === 'next' || action === 'pause') return 'recording-cue-unsupported'
+      } else if ((node.type === 'text' ? node.text : node.display).trim()) text = true
+    }
+  }
+}

package/src/renderer-components.ts

@@ -0,0 +1,30 @@
+import type { BoundRendererExtension, ComponentNode, IRBlock } from './ir.ts'
+import { withProp } from './props.ts'
+
+/** The package of the web renderer when a document names none. */
+export const WEB_RENDERER_PACKAGE = '@lincyaw/web'
+
+/** The renderer extension's renderer of the component: its own plugin's first, or any plugin's for a document's own component. */
+export function findComponentRenderer(node: ComponentNode, extensions: readonly BoundRendererExtension[]): ((node: ComponentNode, block: IRBlock) => unknown) | undefined {
+  const owner = extensions.find(e => e.plugin === node.plugin && e.components?.[node.name])
+    ?? (node.plugin ? undefined : extensions.find(e => e.components?.[node.name]))
+  return owner?.components?.[node.name]
+}
+
+/** What a renderer gives the component: its props, and the node's `durations` as the prop `durations`, kept once in the IR. */
+export function componentProps(node: ComponentNode): Record<string, unknown> {
+  return node.durations ? { ...node.props, durations: node.durations } : node.props
+}
+
+/** Whether a renderer extension renders the component (`findComponentRenderer` finds one). */
+export function hasRendererExtension(node: ComponentNode, extensions: readonly BoundRendererExtension[]): boolean {
+  return findComponentRenderer(node, extensions) !== undefined
+}
+
+/** The component with each prop that `assets` names set to the file's published URL; a file not published keeps its URL. */
+export function withPublishedAssets(node: ComponentNode, publish: (url: string) => string | undefined): ComponentNode {
+  if (!node.assets) return node
+  let props = node.props
+  for (const [path, url] of Object.entries(node.assets)) props = withProp(props, path, publish(url) ?? url)
+  return { ...node, props }
+}

package/src/requests.ts

@@ -0,0 +1,28 @@
+export interface RequestHeaders {
+  host?: string | string[]
+  origin?: string | string[]
+  'sec-fetch-site'?: string | string[]
+}
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+
+function first(value: string | string[] | undefined): string | undefined {
+  return Array.isArray(value) ? value[0] : value
+}
+
+export function hostName(value: string): string {
+  const host = value.includes('://') ? value.slice(value.indexOf('://') + 3) : value
+  if (host.startsWith('[')) return host.slice(0, host.indexOf(']') + 1).toLowerCase()
+  return host.split(':')[0]!.toLowerCase()
+}
+
+export function localRequestRefusal(headers: RequestHeaders, allowedHosts?: true | readonly string[]): string | undefined {
+  if (first(headers['sec-fetch-site']) === 'cross-site') return 'cross-site request'
+  if (allowedHosts === true) return undefined
+  const allowed = (name: string) => LOOPBACK.has(name) || (allowedHosts ?? []).some(host => host.startsWith('.') ? name.endsWith(host) || name === host.slice(1) : name === host.toLowerCase())
+  const host = first(headers.host)
+  if (!host || !allowed(hostName(host))) return `Host ${host ?? '(none)'} is not this machine`
+  const origin = first(headers.origin)
+  if (origin && origin !== 'null' && !allowed(hostName(origin))) return `Origin ${origin} is not this machine`
+  return undefined
+}

package/src/responses.ts

@@ -0,0 +1,49 @@
+export function jsonResponse(data: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(data), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers } })
+}
+
+export function problemResponse(status: number, message: string): Response {
+  return jsonResponse({ error: message }, status)
+}
+
+export function sseResponse(events: AsyncIterable<{ event?: string, data: unknown }>, signal?: AbortSignal): Response {
+  const encoder = new TextEncoder()
+  const iterator = events[Symbol.asyncIterator]()
+  let closed = false
+  const stop = (controller?: ReadableStreamDefaultController<Uint8Array>) => {
+    if (closed) return
+    closed = true
+    void iterator.return?.()
+    try {
+      controller?.close()
+    } catch {
+    }
+  }
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (signal?.aborted) stop(controller)
+      else signal?.addEventListener('abort', () => stop(controller), { once: true })
+    },
+    async pull(controller) {
+      if (closed) return
+      try {
+        const next = await iterator.next()
+        if (closed) return
+        if (next.done) {
+          stop(controller)
+          return
+        }
+        const { event, data } = next.value
+        const lines = `${event ? `event: ${event}\n` : ''}${JSON.stringify(data ?? null).split('\n').map(line => `data: ${line}`).join('\n')}\n\n`
+        controller.enqueue(encoder.encode(lines))
+      } catch (error) {
+        closed = true
+        controller.error(error)
+      }
+    },
+    cancel() {
+      stop()
+    },
+  })
+  return new Response(stream, { headers: { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' } })
+}

package/src/run-outputs.ts

@@ -0,0 +1,15 @@
+import type { RunResult } from './contracts.ts'
+import type { MdastNode } from './ir.ts'
+
+/** Whether a run only displays Markdown, which a renderer can show as prose; `rendered` names the MIME types the renderer draws itself. */
+export function isProseRun(run: RunResult, rendered: (type: string) => boolean = () => false): boolean {
+  const outputs = run.outputs ?? []
+  return outputs.length > 0 && outputs.every(o => (o.output_type === 'display_data' || o.output_type === 'execute_result')
+    && o.data['text/markdown'] !== undefined && !Object.keys(o.data).some(rendered))
+}
+
+/** A run's Markdown output with its raw HTML turned into text, so that the HTML shows as written. */
+export function htmlAsText(node: MdastNode): MdastNode {
+  if (node.type === 'html') return { type: 'text', value: String(node.value ?? '') }
+  return node.children ? { ...node, children: node.children.map(htmlAsText) } : node
+}