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

package/src/node/authoring-actions.ts

@@ -0,0 +1,50 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_JSON_SCHEMA } from '../document-schema.ts'
+import { DOCUMENT_PAGE_DUPLICATION_SCHEMA } from '../contracts/authoring.ts'
+import { DOCUMENT_COMPONENT_IMPACT_COLLECTIONS, DOCUMENT_PARAMETER_MAX_CHANGES, DOCUMENT_PARAMETER_MAX_PATH_DEPTH } from '../contracts/authoring-actions.ts'
+import type { DocumentAuthoringActionRequest, DocumentAuthoringActionReference, DocumentComponentImpactQuery } from '../contracts/authoring-actions.ts'
+
+const id: Schema = { type: 'string', minLength: 1, maxLength: 200 }
+const object = (properties: Record<string, Schema>, required = Object.keys(properties)): Schema => ({ type: 'object', additionalProperties: false, properties, required })
+const action = (type: string, properties: Record<string, Schema>, required = Object.keys(properties)) => object({ type: { const: type }, ...properties }, ['type', ...required])
+const content: Schema = { type: 'array', minItems: 1, maxItems: 100, items: { $ref: '#/$defs/RichTextNode' } }
+const metadata: Schema = { $ref: '#/$defs/JsonObject' }
+const scope: Schema = { oneOf: [object({ kind: { const: 'document' } }), object({ kind: { const: 'page' }, sectionId: id }), object({ kind: { const: 'step' }, stepId: id }), object({ kind: { const: 'steps' }, stepIds: { type: 'array', minItems: 1, maxItems: 1000, items: id } })] }
+const voice: Schema = { oneOf: [{ type: 'null' }, { allOf: [{ $ref: '#/$defs/VoiceSource' }, { properties: { type: { enum: ['none', 'tts'] } } }] }] }
+const parameterPath: Schema = { type: 'array', minItems: 1, maxItems: DOCUMENT_PARAMETER_MAX_PATH_DEPTH, items: { type: 'string', maxLength: 200 } }
+const changes: Schema = { type: 'array', minItems: 1, maxItems: DOCUMENT_PARAMETER_MAX_CHANGES, items: { oneOf: [
+  object({ op: { const: 'set' }, path: parameterPath, value: { $ref: '#/$defs/JsonValue' } }),
+  object({ op: { const: 'remove' }, path: parameterPath }),
+] } }
+
+/** Node-only schema reuses the actual canonical rich-text definitions, not BlockNote data. */
+export const DOCUMENT_AUTHORING_ACTION_SCHEMA: Schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  ...object({ id, source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema, action: { $ref: '#/$defs/AuthoringAction' } }),
+  $defs: { ...(structuredClone(DOCUMENT_JSON_SCHEMA) as Exclude<Schema, boolean>).$defs,
+    AuthoringAction: { oneOf: [
+      action('comment.create', { content, anchor: { oneOf: [{ type: 'null' }, object({ from: { $ref: '#/$defs/TextPoint' }, to: { $ref: '#/$defs/TextPoint' } })] }, metadata, commentMetadata: metadata }, ['content', 'anchor']),
+      action('comment.reply', { threadId: id, content, metadata }, ['threadId', 'content']),
+      action('comment.update', { threadId: id, commentId: id, content, metadata }, ['threadId', 'commentId', 'content']),
+      action('comment.react', { threadId: id, commentId: id, emoji: { type: 'string', minLength: 1, maxLength: 32 }, active: { type: 'boolean' } }),
+      action('comment.resolve', { threadId: id }), action('comment.reopen', { threadId: id }),
+      action('comment.delete', { threadId: id, commentId: id }, ['threadId']),
+      action('voice.set', { scope, source: voice, replaceOverrides: { type: 'boolean' } }, ['scope', 'source']),
+      action('caption.timing.set', { stepId: id, value: { $ref: '#/$defs/CaptionTiming' } }),
+      action('caption.timing.reset', { stepId: id }),
+      action('component.parameters.patch', { blockId: id, changes }),
+      action('component.step-parameters.patch', { blockId: id, stepId: id, changes }),
+      action('component.step-parameters.reset', { blockId: id, stepId: id }),
+      action('component.definition.use', { blockId: id, definitionId: id, changes: { ...changes, minItems: 0 } }, ['blockId', 'definitionId']),
+    ] },
+  },
+}
+export const DOCUMENT_AUTHORING_ACTION_APPLY_SCHEMA: Schema = object({ planId: id, source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, confirmDeletion: { const: true } }, ['planId', 'source', 'digest'])
+export const DOCUMENT_AUTHORING_ACTION_IMPACT_SCHEMA: Schema = object({ planId: id, digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, collection: { enum: [...DOCUMENT_COMPONENT_IMPACT_COLLECTIONS] }, offset: { type: 'integer', minimum: 0, maximum: Number.MAX_SAFE_INTEGER } }, ['planId', 'digest', 'collection'])
+const request = new Validator(structuredClone(DOCUMENT_AUTHORING_ACTION_SCHEMA), '2020-12', false)
+const reference = new Validator(structuredClone(DOCUMENT_AUTHORING_ACTION_APPLY_SCHEMA), '2020-12', false)
+const impact = new Validator(structuredClone(DOCUMENT_AUTHORING_ACTION_IMPACT_SCHEMA), '2020-12', false)
+export function validateDocumentAuthoringAction(value: unknown): value is DocumentAuthoringActionRequest { return request.validate(value).valid }
+export function validateDocumentAuthoringActionReference(value: unknown): value is DocumentAuthoringActionReference { return reference.validate(value).valid }
+export function validateDocumentAuthoringActionImpact(value: unknown): value is DocumentComponentImpactQuery { return impact.validate(value).valid }

package/src/node/authoring-clients.ts

@@ -0,0 +1,14 @@
+import { Validator } from '@cfworker/json-schema'
+import { AUTHORING_CLIENT_ACK_SCHEMA, AUTHORING_CLIENT_CONNECTION_SCHEMA, AUTHORING_CLIENT_OPEN_SCHEMA, AUTHORING_CLIENT_QUERY_SCHEMA, AUTHORING_CLIENT_REPORT_SCHEMA, AUTHORING_CLIENT_REQUEST_QUERY_SCHEMA, AUTHORING_CLIENT_REQUEST_SCHEMA } from '../contracts/authoring-clients.ts'
+import type { AuthoringClientAcknowledgement, AuthoringClientLease, AuthoringClientOpen, AuthoringClientReport, AuthoringClientRequest } from '../contracts/authoring-clients.ts'
+
+const validator = (schema: typeof AUTHORING_CLIENT_REQUEST_SCHEMA) => new Validator(structuredClone(schema), '2020-12', false)
+const request = validator(AUTHORING_CLIENT_REQUEST_SCHEMA), query = validator(AUTHORING_CLIENT_QUERY_SCHEMA), get = validator(AUTHORING_CLIENT_REQUEST_QUERY_SCHEMA)
+const open = validator(AUTHORING_CLIENT_OPEN_SCHEMA), report = validator(AUTHORING_CLIENT_REPORT_SCHEMA), ack = validator(AUTHORING_CLIENT_ACK_SCHEMA), connection = validator(AUTHORING_CLIENT_CONNECTION_SCHEMA)
+export const validateAuthoringClientRequest = (value: unknown): value is AuthoringClientRequest => request.validate(value).valid
+export const validateAuthoringClientQuery = (value: unknown): value is { clientId?: string, after?: string } => query.validate(value).valid
+export const validateAuthoringClientRequestQuery = (value: unknown): value is { clientId: string, epoch: string, requestId: string } => get.validate(value).valid
+export const validateAuthoringClientOpen = (value: unknown): value is AuthoringClientOpen => open.validate(value).valid
+export const validateAuthoringClientReport = (value: unknown): value is AuthoringClientReport => report.validate(value).valid
+export const validateAuthoringClientAcknowledgement = (value: unknown): value is AuthoringClientAcknowledgement => ack.validate(value).valid
+export const validateAuthoringClientLease = (value: unknown): value is AuthoringClientLease => connection.validate(value).valid

package/src/node/document-audio.ts

@@ -0,0 +1,22 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_RECORDING_ADOPTION_SCHEMA, DOCUMENT_AUDIO_INSPECTION_SCHEMA, DOCUMENT_AUDIO_WORKSPACE_IMPORT_SCHEMA, DOCUMENT_WORKSPACE_AUDIO_INSPECTION_SCHEMA, DOCUMENT_MEDIA_CLIP_VALIDATION_SCHEMA, DOCUMENT_MEDIA_CLIP_CHANGE_SCHEMA, DOCUMENT_PRODUCTION_PLAN_SCHEMA } from '../contracts/document-audio.ts'
+import type { DocumentRecordingAdoption, DocumentAudioInspect, DocumentWorkspaceAudioImport, DocumentWorkspaceAudioInspect, DocumentMediaClipValidation, DocumentMediaClipEdit, DocProductionPlanQuery } from '../contracts/document-audio.ts'
+
+const inspectValidator = new Validator(structuredClone(DOCUMENT_AUDIO_INSPECTION_SCHEMA) as unknown as Schema, '2020-12', false)
+const importValidator = new Validator(structuredClone(DOCUMENT_AUDIO_WORKSPACE_IMPORT_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentAudioInspect = (value: unknown): value is DocumentAudioInspect => inspectValidator.validate(value).valid
+export const validateDocumentWorkspaceAudioImport = (value: unknown): value is DocumentWorkspaceAudioImport => importValidator.validate(value).valid
+
+const workspaceInspectValidator = new Validator(structuredClone(DOCUMENT_WORKSPACE_AUDIO_INSPECTION_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentWorkspaceAudioInspect = (value: unknown): value is DocumentWorkspaceAudioInspect => workspaceInspectValidator.validate(value).valid
+
+const clipValidationValidator = new Validator(structuredClone(DOCUMENT_MEDIA_CLIP_VALIDATION_SCHEMA) as unknown as Schema, '2020-12', false)
+const clipChangeValidator = new Validator(structuredClone(DOCUMENT_MEDIA_CLIP_CHANGE_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentMediaClipValidation = (value: unknown): value is DocumentMediaClipValidation => clipValidationValidator.validate(value).valid
+export const validateDocumentMediaClipEdit = (value: unknown): value is DocumentMediaClipEdit => clipChangeValidator.validate(value).valid
+const productionPlanValidator = new Validator(structuredClone(DOCUMENT_PRODUCTION_PLAN_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentProductionPlanQuery = (value: unknown): value is DocProductionPlanQuery => productionPlanValidator.validate(value).valid
+
+const recordingValidator = new Validator(structuredClone(DOCUMENT_RECORDING_ADOPTION_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentRecordingAdoption = (value: unknown): value is DocumentRecordingAdoption => recordingValidator.validate(value).valid

package/src/node/document-history.ts

@@ -0,0 +1,11 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_HISTORY_CHANGE_SCHEMA, DOCUMENT_HISTORY_QUERY_SCHEMA, DOCUMENT_HISTORY_READ_SCHEMA } from '../contracts/document-history.ts'
+import type { DocumentHistoryChange, DocumentHistoryQuery, DocumentHistoryRead } from '../contracts/document-history.ts'
+
+const query = new Validator(structuredClone(DOCUMENT_HISTORY_QUERY_SCHEMA) as unknown as Schema, '2020-12', false)
+const read = new Validator(structuredClone(DOCUMENT_HISTORY_READ_SCHEMA) as unknown as Schema, '2020-12', false)
+const change = new Validator(structuredClone(DOCUMENT_HISTORY_CHANGE_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentHistoryQuery = (value: unknown): value is DocumentHistoryQuery => query.validate(value).valid
+export const validateDocumentHistoryRead = (value: unknown): value is DocumentHistoryRead => read.validate(value).valid
+export const validateDocumentHistoryChange = (value: unknown): value is DocumentHistoryChange => change.validate(value).valid

package/src/node/document-image.ts

@@ -0,0 +1,8 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_WORKSPACE_IMAGE_INSPECTION_SCHEMA, DOCUMENT_WORKSPACE_IMAGE_IMPORT_SCHEMA } from '../contracts/document-image.ts'
+import type { DocumentWorkspaceImageInspect, DocumentWorkspaceImageImport } from '../contracts/document-image.ts'
+const inspect = new Validator(structuredClone(DOCUMENT_WORKSPACE_IMAGE_INSPECTION_SCHEMA) as unknown as Schema, '2020-12', false)
+const importImage = new Validator(structuredClone(DOCUMENT_WORKSPACE_IMAGE_IMPORT_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentWorkspaceImageInspect = (value: unknown): value is DocumentWorkspaceImageInspect => inspect.validate(value).valid
+export const validateDocumentWorkspaceImageImport = (value: unknown): value is DocumentWorkspaceImageImport => importImage.validate(value).valid

package/src/node/document-reads.ts

@@ -0,0 +1,10 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_OUTLINE_QUERY_SCHEMA, DOCUMENT_PART_QUERY_SCHEMA, DOCUMENT_READ_MAX_REQUEST_CHARS } from '../contracts/document-reads.ts'
+import type { DocumentOutlineQuery, DocumentPartQuery } from '../contracts/document-reads.ts'
+
+const outline = new Validator(structuredClone(DOCUMENT_OUTLINE_QUERY_SCHEMA) as unknown as Schema, '2020-12', false)
+const part = new Validator(structuredClone(DOCUMENT_PART_QUERY_SCHEMA) as unknown as Schema, '2020-12', false)
+const bounded = (value: unknown) => { try { return JSON.stringify(value).length <= DOCUMENT_READ_MAX_REQUEST_CHARS } catch { return false } }
+export function validateDocumentOutlineQuery(value: unknown): value is DocumentOutlineQuery { return bounded(value) && outline.validate(value).valid }
+export function validateDocumentPartQuery(value: unknown): value is DocumentPartQuery { return bounded(value) && part.validate(value).valid }

package/src/node/document-voice.ts

@@ -0,0 +1,7 @@
+import { Validator } from '@cfworker/json-schema'
+import type { Schema } from '@cfworker/json-schema'
+import { DOCUMENT_VOICE_CATALOG_SCHEMA } from '../contracts/document-voice.ts'
+import type { DocumentVoiceCatalogQuery } from '../contracts/document-voice.ts'
+
+const validator = new Validator(structuredClone(DOCUMENT_VOICE_CATALOG_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateDocumentVoiceCatalogQuery = (value: unknown): value is DocumentVoiceCatalogQuery => validator.validate(value).valid

package/src/node/ffmpeg.ts

@@ -0,0 +1,29 @@
+import { spawnSync } from 'node:child_process'
+
+export interface Ffmpeg {
+  /** The program, as it is run. */
+  file: string
+  /** The names of its encoders (`libx264`, `libvpx-vp9`, `aac`, `libopus`…). */
+  encoders: Set<string>
+}
+
+let found: Ffmpeg | null | undefined
+
+/**
+ * FFmpeg as the author installed it: `PRESMIUM_FFMPEG`, else `ffmpeg` on the path; undefined when it does not run.
+ * Presmium does not ship it; it encodes the lecture video with it when it is there (`ffmpegInstallHint` says how).
+ */
+export function findFfmpeg(): Ffmpeg | undefined {
+  if (found !== undefined) return found ?? undefined
+  const file = process.env.PRESMIUM_FFMPEG || 'ffmpeg'
+  const run = spawnSync(file, ['-hide_banner', '-encoders'], { encoding: 'utf8', timeout: 10_000 })
+  found = run.status === 0 ? { file, encoders: new Set([...run.stdout.matchAll(/^ [A-Z.]{6} (\S+)/gm)].map(m => m[1]!)) } : null
+  return found ?? undefined
+}
+
+/** The one command that installs FFmpeg on this system. */
+export function ffmpegInstallCommand(platform: NodeJS.Platform = process.platform): string {
+  if (platform === 'darwin') return 'brew install ffmpeg'
+  if (platform === 'win32') return 'winget install --id Gyan.FFmpeg'
+  return 'sudo apt install ffmpeg'
+}

package/src/node/file-version.ts

@@ -0,0 +1,6 @@
+import type { BigIntStats } from 'node:fs'
+
+/** A local file's identity and observed contents, including replacements that preserve its modification time. */
+export function fileVersion(stat: Pick<BigIntStats, 'dev' | 'ino' | 'size' | 'mtimeNs' | 'ctimeNs'>): string {
+  return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(':')
+}

package/src/node/fonts.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import { createRequire, findPackageJSON } from 'node:module'
+
+export const FONT_LICENSE = 'presmium/fonts/LICENSE'
+
+const FONT_COPYRIGHTS: Record<string, string> = {
+  '@fontsource/ibm-plex-mono': 'IBM Plex Mono: Copyright 2017 IBM Corp. All rights reserved.',
+  '@fontsource/ibm-plex-sans': 'IBM Plex Sans: Copyright 2019 IBM Corp. All rights reserved.',
+  '@fontsource/source-serif-4': 'Source Serif 4: Copyright 2014 - 2021 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name \'Source\'.',
+}
+
+export function fontLicense(from: string | URL): string {
+  const manifest = findPackageJSON('@lincyaw/host', from)
+  if (!manifest) throw new Error('@lincyaw/host is not installed')
+  const { dependencies = {} } = JSON.parse(readFileSync(manifest, 'utf8')) as { dependencies?: Record<string, string> }
+  const require = createRequire(manifest)
+  const files = Object.keys(dependencies).filter(name => name.startsWith('@fontsource/')).sort().map((name) => {
+    const copyright = FONT_COPYRIGHTS[name] ? `${FONT_COPYRIGHTS[name]}\n\n` : ''
+    return `${name}\n\n${copyright}${readFileSync(require.resolve(`${name}/LICENSE`), 'utf8').trim()}\n`
+  })
+  return [`The fonts of this site, from Fontsource, with their copyrights and licenses (SIL Open Font License 1.1).\n`, ...files].join(`\n${'='.repeat(78)}\n\n`)
+}

package/src/node/index.ts

@@ -1,133 +1,29 @@
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync } from 'node:fs'
-import { createRequire, findPackageJSON } from 'node:module'
-import { dirname, join, sep } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import type { LocalAsset } from '../ir.ts'
-
-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
-}
-
-export const FONT_LICENSE = 'presmium/fonts/LICENSE'
-
-const FONT_COPYRIGHTS: Record<string, string> = {
-  '@fontsource/ibm-plex-mono': 'IBM Plex Mono: Copyright 2017 IBM Corp. All rights reserved.',
-  '@fontsource/ibm-plex-sans': 'IBM Plex Sans: Copyright 2019 IBM Corp. All rights reserved.',
-  '@fontsource/source-serif-4': 'Source Serif 4: Copyright 2014 - 2021 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name \'Source\'.',
-}
-
-export function fontLicense(from: string | URL): string {
-  const manifest = findPackageJSON('@lincyaw/host', from)
-  if (!manifest) throw new Error('@lincyaw/host is not installed')
-  const { dependencies = {} } = JSON.parse(readFileSync(manifest, 'utf8')) as { dependencies?: Record<string, string> }
-  const require = createRequire(manifest)
-  const files = Object.keys(dependencies).filter(name => name.startsWith('@fontsource/')).sort().map((name) => {
-    const copyright = FONT_COPYRIGHTS[name] ? `${FONT_COPYRIGHTS[name]}\n\n` : ''
-    return `${name}\n\n${copyright}${readFileSync(require.resolve(`${name}/LICENSE`), 'utf8').trim()}\n`
-  })
-  return [`The fonts of this site, from Fontsource, with their copyrights and licenses (SIL Open Font License 1.1).\n`, ...files].join(`\n${'='.repeat(78)}\n\n`)
-}
-
-export const TYPESCRIPT_IMPORT: readonly string[] = ['--import', new URL('./strip-types.mjs', import.meta.url).href]
-
-const PROVIDED = /^(?:vue|@vue\/.*|vitepress|@slidev\/.*)$/
-const PRESMIUM = /^@lincyaw\//
-const IMPORT = /(?:^|\n)\s*(?:import|export)(?!\s+type\b)[^'"`;]*?\bfrom\s*['"]([^'"./][^'"]*)['"]|(?:^|\n)\s*import\s*['"]([^'"./][^'"]*)['"]|\bimport\(\s*['"]([^'"./][^'"]*)['"]\s*\)/g
-const SOURCE = /\.(?:[cm]?[jt]s|vue)$/
-const DECLARATION = /\.d\.[cm]?ts$/
-const STYLE = /\.(?:css|scss|sass|less|styl)$/
-const NOT_BROWSER = new Set(['node', 'bin', 'test', 'fixtures', 'node_modules'])
-
-export function preBundle(root: string, packages: Iterable<string>): string[] {
-  return optimizeDeps(root, packages).include
-}
-
-export function optimizeDeps(root: string, packages: Iterable<string>): { include: string[], exclude: string[] } {
-  const include = new Set<string>()
-  const exclude = new Set<string>()
-  const seen = new Set<string>()
-  const visit = (dir: string): void => {
-    const real = realpathSync(dir)
-    if (seen.has(real) || !real.split(sep).includes('node_modules')) return
-    seen.add(real)
-    const { name, imports, presmium } = browserDependencies(real)
-    exclude.add(name)
-    if (imports.length > 0) linkPackage(root, name, real)
-    for (const specifier of imports) include.add(`${name} > ${specifier}`)
-    for (const dependency of presmium) {
-      const manifest = installedManifest(dependency, real)
-      if (manifest) visit(dirname(manifest))
-    }
-  }
-  for (const dir of packages) if (existsSync(join(dir, 'package.json'))) visit(dir)
-  return { include: [...include].sort(), exclude: [...exclude].sort() }
-}
-
-function installedManifest(name: string, dir: string): string | undefined {
-  try {
-    return findPackageJSON(name, pathToFileURL(join(dir, 'package.json')))
-  } catch {
-    return undefined
-  }
-}
-
-export function packageOf(file: string): string | undefined {
-  const manifest = findPackageJSON(pathToFileURL(file))
-  return manifest && dirname(manifest)
-}
-
-function linkPackage(root: string, name: string, dir: string): void {
-  const link = join(root, 'node_modules', name)
-  const stat = lstatSync(link, { throwIfNoEntry: false })
-  if (stat?.isSymbolicLink() && readlinkSync(link) === dir) return
-  if (stat && !stat.isSymbolicLink()) return
-  rmSync(link, { force: true })
-  mkdirSync(dirname(link), { recursive: true })
-  symlinkSync(dir, link, 'junction')
-}
-
-interface BrowserDependencies {
-  name: string
-  imports: string[]
-  presmium: string[]
-}
-
-const dependencies = new Map<string, BrowserDependencies>()
-function browserDependencies(dir: string): BrowserDependencies {
-  let found = dependencies.get(dir)
-  if (!found) {
-    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name: string, dependencies?: Record<string, string>, peerDependencies?: Record<string, string> }
-    const own = (specifier: string) => Object.hasOwn(pkg.dependencies ?? {}, packageName(specifier))
-    const specifiers = [...browserImports(dir)]
-    found = {
-      name: pkg.name,
-      imports: specifiers.filter(specifier => own(specifier) && !PROVIDED.test(packageName(specifier)) && !PRESMIUM.test(specifier) && !STYLE.test(specifier)),
-      presmium: [...new Set(specifiers.filter(specifier => PRESMIUM.test(specifier)).map(packageName))]
-        .filter(name => Object.hasOwn({ ...pkg.dependencies, ...pkg.peerDependencies }, name)),
-    }
-    dependencies.set(dir, found)
-  }
-  return found
-}
-
-function browserImports(dir: string, found = new Set<string>(), top = true): Set<string> {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const path = join(dir, entry.name)
-    if (entry.isDirectory()) {
-      if (!NOT_BROWSER.has(entry.name)) browserImports(path, found, false)
-    } else if (SOURCE.test(entry.name) && !DECLARATION.test(entry.name) && !(top && entry.name === 'vite.config.ts')) {
-      for (const match of readFileSync(path, 'utf8').matchAll(IMPORT)) found.add((match[1] ?? match[2] ?? match[3])!)
-    }
-  }
-  return found
-}
-
-function packageName(specifier: string): string {
-  const parts = specifier.split('/')
-  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]!
-}
+export { copyPublished, productionAssetFile } from './assets.ts'
+export { fileVersion } from './file-version.ts'
+export { DOCUMENT_CHANGE_JSON_SCHEMA, validateDocumentChange, validateDocumentPageChange, validateDocumentPageChangeApply, validateDocumentPageDuplication, validateDocumentPageDuplicationApply } from '../authoring.ts'
+export { validateDocumentOutlineQuery, validateDocumentPartQuery } from './document-reads.ts'
+export { DOCUMENT_AUTHORING_ACTION_SCHEMA, DOCUMENT_AUTHORING_ACTION_APPLY_SCHEMA, DOCUMENT_AUTHORING_ACTION_IMPACT_SCHEMA, validateDocumentAuthoringAction, validateDocumentAuthoringActionReference, validateDocumentAuthoringActionImpact } from './authoring-actions.ts'
+export { validateDocumentTranscriptionRequest } from './transcription.ts'
+export { validateDocumentRecordingAdoption, validateDocumentAudioInspect, validateDocumentWorkspaceAudioImport, validateDocumentWorkspaceAudioInspect, validateDocumentMediaClipValidation, validateDocumentMediaClipEdit, validateDocumentProductionPlanQuery } from './document-audio.ts'
+export { validateDocumentVoiceCatalogQuery } from './document-voice.ts'
+export { createVoiceoverOwner, VoiceoverOperationError, validateVoiceoverStart, validateVoiceoverStatus, validateVoiceoverJobQuery, validateVoicePreviewCheck, validateVoicePreviewStart } from './voiceover.ts'
+export { createVoiceoverRoutes } from './voiceover-routes.ts'
+export { validateTranscriptionAdoptionDraft, validateTranscriptionAdoptionApply } from './transcription-adoption.ts'
+export { FONT_LICENSE, fontLicense } from './fonts.ts'
+export { findPackageBin, importSpecifier, literalGlob, packageOf, playwrightChromium, TYPESCRIPT_IMPORT } from './packages.ts'
+export { ffmpegInstallCommand, findFfmpeg } from './ffmpeg.ts'
+export type { Ffmpeg } from './ffmpeg.ts'
+export { bracketIPv6, lanAddresses } from './network.ts'
+export { forEachLine } from './lines.ts'
+export { isInside } from './paths.ts'
+export { backgroundPriority, machineState, NODE_RESOURCE_ARGS, nodeResourceArgs, resourceEnvironment, spawnBackgroundNode, spawnInteractiveNode, threadBudget } from './resources.ts'
+export type { MachineState, ResourceClass } from './resources.ts'
+export { irRevision } from './revision.ts'
+export { findInstalledPackage } from './installed-packages.ts'
+export { directSandbox, minimalRunEnv, RUN_REQUEST_FILE, RUN_RESULT_PREFIX, runResultFile } from './run-directory.ts'
+export { validateDocumentHistoryQuery, validateDocumentHistoryRead, validateDocumentHistoryChange } from './document-history.ts'
+export { validateAuthoringClientRequest, validateAuthoringClientQuery, validateAuthoringClientRequestQuery, validateAuthoringClientOpen, validateAuthoringClientReport, validateAuthoringClientAcknowledgement, validateAuthoringClientLease } from './authoring-clients.ts'
+export { validateProjectPlan, validateProjectApply } from './projects.ts'
+export { validateDocumentWorkspaceImageInspect, validateDocumentWorkspaceImageImport } from './document-image.ts'
+export { systemLocale } from './locale.ts'
+export { OperatorSpeechSettings, operatorSpeechSecrets, SpeechSettingsError } from './operator-speech.ts'

package/src/node/installed-packages.ts

@@ -0,0 +1,11 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The real directory of the package `name` installed in a `node_modules` at or above `from`, as Node resolves it. */
+export function findInstalledPackage(name: string, from: string): string | undefined {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const candidate = join(dir, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) return realpathSync(candidate)
+    if (dirname(dir) === dir) return undefined
+  }
+}

package/src/node/lines.ts

@@ -0,0 +1,24 @@
+import type { Readable } from 'node:stream'
+
+// Terminal colours and cursor moves, which a log shown on a page does not draw.
+const ESCAPES = /\x1B\[[0-?]*[ -/]*[@-~]|\x1B\][^\x07]*\x07/g
+
+/** Calls `each` with every line `stream` writes (carriage returns end a line too), without terminal escapes. */
+export function forEachLine(stream: Readable | null | undefined, each: (line: string) => void): void {
+  if (!stream) return
+  let rest = ''
+  stream.setEncoding('utf8')
+  stream.on('data', (chunk: string) => {
+    const parts = (rest + chunk).split(/\r\n|\r|\n/)
+    rest = parts.pop() ?? ''
+    for (const part of parts) {
+      const line = part.replace(ESCAPES, '')
+      if (line.trim()) each(line)
+    }
+  })
+  stream.on('end', () => {
+    const line = rest.replace(ESCAPES, '')
+    if (line.trim()) each(line)
+    rest = ''
+  })
+}

package/src/node/locale.ts

@@ -0,0 +1,7 @@
+import type { Locale } from '../contracts/locale.ts'
+
+/** The language of command-line output: the system's (`LC_ALL`, `LC_MESSAGES`, `LANG`, else `Intl`'s); `zh*` is zh-CN. */
+export function systemLocale(env: NodeJS.ProcessEnv = process.env): Locale {
+  const tag = env.LC_ALL || env.LC_MESSAGES || env.LANG || Intl.DateTimeFormat().resolvedOptions().locale
+  return /^zh/i.test(tag) ? 'zh-CN' : 'en'
+}

package/src/node/network.ts

@@ -0,0 +1,11 @@
+import { networkInterfaces } from 'node:os'
+
+/** This machine's IPv4 addresses on its local networks, for printing the addresses other devices can use. */
+export function lanAddresses(): string[] {
+  return Object.values(networkInterfaces()).flatMap(entries => entries ?? []).filter(entry => entry.family === 'IPv4' && !entry.internal).map(entry => entry.address)
+}
+
+/** The host as a URL writes it: an IPv6 address in brackets. */
+export function bracketIPv6(host: string): string {
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host
+}

package/src/node/operator-speech.ts

@@ -0,0 +1,91 @@
+import { createRequire } from 'node:module'
+import { randomUUID } from 'node:crypto'
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { SpeechSettingsAnswer, SpeechSettingsChange } from '../contracts/speech-settings.ts'
+
+const KEY = 'PRESMIUM_SPEECH_VOLCENGINE_KEY', APPID = 'PRESMIUM_SPEECH_VOLCENGINE_APPID'
+const MAX_BYTES = 16384
+const lockfile = createRequire(import.meta.url)('proper-lockfile') as { lock(file: string, options: { realpath: boolean, retries: number }): Promise<() => Promise<void>> }
+interface Stored { version: 1, revision: string, key?: string, appId?: string }
+const empty = (): Stored => ({ version: 1, revision: 'none' })
+
+export class SpeechSettingsError extends Error {
+  readonly code: 'speech-settings-conflict' | 'speech-settings-invalid' | 'speech-settings-unavailable' | 'speech-settings-busy'
+  constructor(code: SpeechSettingsError['code']) { super(code); this.code = code }
+}
+
+/** One operator-owned file; no values leave this module except through the Node secret resolver. */
+export class OperatorSpeechSettings {
+  readonly #file: string | undefined
+  readonly #fallback: (name: string) => string | undefined
+  constructor(directory: string | undefined, fallback: (name: string) => string | undefined) {
+    this.#file = directory ? join(directory, 'speech', 'credentials.json') : undefined
+    this.#fallback = fallback
+  }
+  #read(): Stored {
+    if (!this.#file) return empty()
+    let fd: number | undefined
+    try {
+      fd = openSync(this.#file, constants.O_RDONLY | constants.O_NOFOLLOW)
+      const stat = fstatSync(fd)
+      if (!stat.isFile() || stat.size > MAX_BYTES) throw new SpeechSettingsError('speech-settings-unavailable')
+      const value = JSON.parse(readFileSync(fd, 'utf8')) as Stored
+      if (value?.version !== 1 || typeof value.revision !== 'string' || value.key !== undefined && typeof value.key !== 'string' || value.appId !== undefined && (typeof value.appId !== 'string' || !/^\d{1,32}$/.test(value.appId))) throw new SpeechSettingsError('speech-settings-unavailable')
+      return value
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return empty()
+      throw new SpeechSettingsError('speech-settings-unavailable')
+    } finally { if (fd !== undefined) closeSync(fd) }
+  }
+  secret = (name: string): string | undefined => {
+    if (name !== KEY && name !== APPID) return this.#fallback(name)
+    const saved = this.#read()
+    // API-key authentication must not inherit a different environment credential's App ID.
+    if (name === APPID && saved.key) return saved.appId
+    return (name === KEY ? saved.key : undefined) ?? this.#fallback(name)
+  }
+  read(): SpeechSettingsAnswer {
+    const value = this.#read(), key = value.key ?? this.#fallback(KEY)?.trim()
+    return { provider: 'volcengine', model: 'seed-tts-2.0', revision: value.revision, configured: Boolean(key), appIdConfigured: Boolean(value.key ? value.appId : this.#fallback(APPID)), source: value.key ? 'saved' : key ? 'environment' : 'none', stored: Boolean(value.key), writable: Boolean(this.#file), verification: 'configuration-only' }
+  }
+  async change(change: SpeechSettingsChange): Promise<SpeechSettingsAnswer> {
+    if (!this.#file) throw new SpeechSettingsError('speech-settings-unavailable')
+    const directory = dirname(this.#file)
+    try {
+      mkdirSync(directory, { recursive: true, mode: 0o700 })
+      if (lstatSync(directory).isSymbolicLink()) throw new Error('unsafe-directory')
+    } catch { throw new SpeechSettingsError('speech-settings-unavailable') }
+    let release: () => Promise<void>
+    try { release = await lockfile.lock(this.#file, { realpath: false, retries: 0 }) }
+    catch { throw new SpeechSettingsError('speech-settings-busy') }
+    let temporary: string | undefined
+    try {
+      const previous = this.#read()
+      if (change.revision !== previous.revision) throw new SpeechSettingsError('speech-settings-conflict')
+      let next: Stored = { version: 1, revision: randomUUID() }
+      if (change.action === 'save') {
+        const key = change.apiKey?.trim() || previous.key || this.#fallback(KEY)?.trim()
+        if (!key || !/^[\x21-\x7e]{8,8192}$/.test(key)) throw new SpeechSettingsError('speech-settings-invalid')
+        const appId = change.appId?.trim() ?? (change.apiKey?.trim() ? undefined : previous.key ? previous.appId : this.#fallback(APPID)?.trim())
+        if (appId && !/^\d{1,32}$/.test(appId)) throw new SpeechSettingsError('speech-settings-invalid')
+        next = { ...next, key, ...appId ? { appId } : {} }
+      }
+      temporary = `${this.#file}.${randomUUID()}.tmp`
+      writeFileSync(temporary, `${JSON.stringify(next)}\n`, { mode: 0o600, flag: 'wx' })
+      renameSync(temporary, this.#file)
+      temporary = undefined
+      return this.read()
+    } catch (error) {
+      if (error instanceof SpeechSettingsError) throw error
+      throw new SpeechSettingsError('speech-settings-unavailable')
+    } finally {
+      if (temporary) rmSync(temporary, { force: true })
+      await release()
+    }
+  }
+}
+
+export function operatorSpeechSecrets(directory: string | undefined, fallback: (name: string) => string | undefined): (name: string) => string | undefined {
+  return new OperatorSpeechSettings(directory, fallback).secret
+}

package/src/node/packages.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire, findPackageJSON } from 'node:module'
+import { dirname, isAbsolute, join, relative, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const TYPESCRIPT_IMPORT: readonly string[] = ['--import', new URL('./strip-types.mjs', import.meta.url).href]
+
+/**
+ * The import specifier of `file` in a module generated in `dir`: relative where it can be (Vite's dependency scan does
+ * not follow an import written as an absolute path), else absolute (another drive on Windows).
+ */
+export function importSpecifier(dir: string, file: string): string {
+  const path = relative(dir, file)
+  if (isAbsolute(path)) return file
+  const posix = path.split(sep).join('/')
+  return posix.startsWith('.') ? posix : `./${posix}`
+}
+
+/** `file` as a glob that matches only it: Vite's `optimizeDeps.entries` are globs. */
+export function literalGlob(file: string): string {
+  return file.split(sep).join('/').replace(/[\\*?[\]{}()!@+|]/g, '\\$&')
+}
+
+export function packageOf(file: string): string | undefined {
+  const manifest = findPackageJSON(pathToFileURL(file))
+  return manifest && dirname(manifest)
+}
+
+function manifestOf(name: string, from: string): string | undefined {
+  const require = createRequire(from)
+  try {
+    return require.resolve(`${name}/package.json`)
+  } catch {}
+  let dir: string
+  try {
+    dir = dirname(require.resolve(name))
+  } catch {
+    return undefined
+  }
+  for (; dirname(dir) !== dir; dir = dirname(dir)) {
+    const file = join(dir, 'package.json')
+    if (existsSync(file) && (JSON.parse(readFileSync(file, 'utf8')) as { name?: string }).name === name) return file
+  }
+  return undefined
+}
+
+/** The file of the package's command `command` (its `bin`), the package as Node resolves it from `from`; undefined when either is missing. */
+export function findPackageBin(name: string, command: string, from: string): string | undefined {
+  const manifest = manifestOf(name, from)
+  if (!manifest) return undefined
+  const { bin } = JSON.parse(readFileSync(manifest, 'utf8')) as { bin?: string | Record<string, string> }
+  const file = typeof bin === 'string' ? bin : bin?.[command]
+  return file === undefined ? undefined : join(dirname(manifest), file)
+}
+
+/**
+ * Playwright's Chromium (`playwright-chromium`), as the deck installs it, else as `fallbackFrom` (a module's URL or a
+ * `package.json`) finds it.
+ */
+export async function playwrightChromium<T = unknown>(deckDir: string, fallbackFrom?: string): Promise<T> {
+  for (const from of [join(deckDir, 'package.json'), ...fallbackFrom ? [fallbackFrom] : []]) {
+    let entry: string
+    try {
+      entry = createRequire(from).resolve('playwright-chromium')
+    } catch {
+      continue
+    }
+    const loaded = await import(pathToFileURL(entry).href) as { chromium?: T, default?: { chromium?: T } }
+    const chromium = loaded.chromium ?? loaded.default?.chromium
+    if (chromium) return chromium
+    throw new Error('playwright-chromium does not export its Chromium browser')
+  }
+  throw new Error('this needs playwright-chromium: install it in the deck (and its browser with pnpm exec playwright install chromium)')
+}

package/src/node/paths.ts

@@ -0,0 +1,7 @@
+import { isAbsolute, relative, sep } from 'node:path'
+
+/** Whether path is root itself or lies under it; symbolic links are not resolved. */
+export function isInside(path: string, root: string): boolean {
+  const rel = relative(root, path)
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+}

package/src/node/projects.ts

@@ -0,0 +1,7 @@
+import type { Schema } from '@cfworker/json-schema'
+import { Validator } from '@cfworker/json-schema'
+import { PROJECT_APPLY_SCHEMA, PROJECT_PLAN_SCHEMA } from '../contracts/projects.ts'
+import type { ProjectApply, ProjectPlanRequest } from '../contracts/projects.ts'
+const plan = new Validator(structuredClone(PROJECT_PLAN_SCHEMA) as unknown as Schema, '2020-12', false), apply = new Validator(structuredClone(PROJECT_APPLY_SCHEMA) as unknown as Schema, '2020-12', false)
+export const validateProjectPlan = (value: unknown): value is ProjectPlanRequest => plan.validate(value).valid
+export const validateProjectApply = (value: unknown): value is ProjectApply => apply.validate(value).valid