@lincyaw/compiler 1.0.0-rc.11 → 1.0.0-rc.111

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincyaw/compiler",
3
- "version": "1.0.0-rc.11",
3
+ "version": "1.0.0-rc.111",
4
4
  "description": "Presmium's compiler: structured JSON documents to runtime IR, plugin loading, compile-time execution and its cache, checks and the renderers",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -31,14 +31,22 @@
31
31
  "dependencies": {
32
32
  "content-disposition": "1.0.0",
33
33
  "cors": "2.8.5",
34
+ "hast-util-from-html": "2.0.3",
35
+ "hast-util-to-mdast": "^10.1.3",
34
36
  "jiti": "^2.7.0",
37
+ "mammoth": "^1.13.0",
38
+ "mdast-util-from-markdown": "2.1.0",
39
+ "mdast-util-gfm": "3.1.0",
40
+ "mdast-util-math": "3.0.0",
41
+ "mdast-util-to-markdown": "2.2.0",
42
+ "micromark-extension-gfm": "3.0.0",
43
+ "micromark-extension-math": "3.1.0",
35
44
  "myst-common": "1.10.1",
36
45
  "myst-transforms": "1.3.51",
37
- "resolve.exports": "2.0.4",
38
46
  "semver": "^7.8.5",
39
47
  "send": "1.2.1",
40
48
  "yaml": "^2.9.1",
41
- "@lincyaw/kernel": "1.0.0-rc.11"
49
+ "@lincyaw/kernel": "1.0.0-rc.111"
42
50
  },
43
51
  "devDependencies": {
44
52
  "@types/content-disposition": "^0.5.9",
@@ -5,6 +5,7 @@ import type { CheckContext, Finding, RunResult } from '@lincyaw/kernel'
5
5
  import { build } from './build.ts'
6
6
  import type { BuildReport } from './build.ts'
7
7
  import type { Compilation } from './compiler.ts'
8
+ import { rendererChecks } from './renderers.ts'
8
9
  import { frontmatterLine } from './source-lines.ts'
9
10
 
10
11
  export function checkContext(compilation: Compilation): CheckContext {
@@ -20,7 +21,7 @@ export function checkContext(compilation: Compilation): CheckContext {
20
21
  }
21
22
  }
22
23
 
23
- /** The plugins' checks and the publication checks; a crashed check or a duplicate check ID becomes a finding. */
24
+ /** The plugins' checks, the publication checks and the renderers'; a crashed check or a duplicate check ID becomes a finding. */
24
25
  export async function runAllChecks(compilation: Compilation, options: { externalLinks?: boolean } = {}): Promise<Finding[]> {
25
26
  const { entry } = compilation
26
27
  const text = await readFile(entry, 'utf8').catch(() => '')
@@ -42,6 +43,7 @@ export async function runAllChecks(compilation: Compilation, options: { external
42
43
  findings.push(finding.source ? finding : { ...finding, source: places.get(finding.checkId) ?? { file: entry, line: 1 } })
43
44
  }
44
45
  findings.push(...await compilation.publishChecks({ externalLinks: options.externalLinks }))
46
+ findings.push(...await rendererChecks(compilation))
45
47
  return findings
46
48
  }
47
49
 
package/src/compiler.ts CHANGED
@@ -278,9 +278,11 @@ export class Compiler {
278
278
  const document = validated.document
279
279
  const headmatter = withHeadmatter({ ...document.metadata }, this.options.headmatter)
280
280
  const defaultVoice = document.production.defaults.voiceSource
281
- const lecture = isRecord((headmatter.renderers as Record<string, unknown> | undefined)?.lecture) ? (headmatter.renderers as Record<string, Record<string, unknown>>).lecture : {}
281
+ const declared = isRecord((headmatter.renderers as Record<string, unknown> | undefined)?.lecture)
282
+ const lecture = declared ? (headmatter.renderers as Record<string, Record<string, unknown>>).lecture : {}
282
283
  if (lecture && Object.hasOwn(lecture, 'script')) throw new Error('/metadata/renderers/lecture/script: External lecture scripts are not supported. Author narration in lecture.json narrations and bind it through each step narrationIds.')
283
- if (defaultVoice?.type === 'tts' || document.production.defaults.trailingPauseMs !== undefined || Object.keys(lecture ?? {}).length) headmatter.renderers = { ...(isRecord(headmatter.renderers) ? headmatter.renderers : {}), lecture: { ...lecture, ...defaultVoice?.type === 'tts' ? { voice: defaultVoice.voice } : {}, ...document.production.defaults.trailingPauseMs !== undefined ? { gap: document.production.defaults.trailingPauseMs } : {} } }
284
+ // The production defaults configure the lecture form where the document builds it; they never add the form.
285
+ if (declared && (defaultVoice?.type === 'tts' || document.production.defaults.trailingPauseMs !== undefined || Object.keys(lecture ?? {}).length)) headmatter.renderers = { ...(isRecord(headmatter.renderers) ? headmatter.renderers : {}), lecture: { ...lecture, ...defaultVoice?.type === 'tts' ? { voice: defaultVoice.voice } : {}, ...document.production.defaults.trailingPauseMs !== undefined ? { gap: document.production.defaults.trailingPauseMs } : {} } }
284
286
  const lang = typeof headmatter.lang === 'string' && headmatter.lang.trim() ? headmatter.lang.trim() : DEFAULT_LANG
285
287
  const inputs = new CompileInputs(workspaceRoot, this.#committed)
286
288
  const presmium = isRecord(headmatter.presmium) ? headmatter.presmium : {}
@@ -317,7 +319,7 @@ export class Compiler {
317
319
  return { workspace, headmatter, lang, plugins, configOf, service, execute, inputs, findings, report, at, signal: options.signal, document, rawSource: read }
318
320
  }
319
321
 
320
- /** Registers each plugin's directives, roles, anchor resolvers, executors, environment providers and components. */
322
+ /** Collects the plugins' anchor resolvers, executors, environment providers and components. */
321
323
  async #collectContributions(run: CompileRun): Promise<Contributions> {
322
324
  const { plugins, configOf, execute, report, at } = run
323
325
  const resolvers = createAnchorResolverRegistry()
@@ -523,8 +525,10 @@ export class Compiler {
523
525
  const dirs = new Set(operators.plugins.map(loaded => loaded.dir))
524
526
  const plugins = [...operators.plugins, ...deck.plugins.filter(loaded => !dirs.has(loaded.dir))]
525
527
  const problems = [...operators.problems, ...deck.problems]
526
- this.#plugins = { key, plugins, problems }
527
- return this.#plugins
528
+ const loaded = { key, plugins, problems }
529
+ // Failed discovery must be retried after a package is installed or repaired.
530
+ this.#plugins = problems.length === 0 ? loaded : undefined
531
+ return loaded
528
532
  }
529
533
 
530
534
  }
@@ -1,6 +1,6 @@
1
1
  import { captionSourceFingerprint, documentColorValue, isRecord, voiceTarget } from '@lincyaw/kernel'
2
- import type { CodeNode, ComponentNode, Definition, DocumentBlock, Finding, InlineNode, IRBlock, IRSection, JsonObject, MdastNode, NarrationNode, RichTextNode, SourcePos, TeachingDocument, TextStyle, VisualState } from '@lincyaw/kernel'
3
- import { relative, resolve, sep } from 'node:path'
2
+ import type { CodeNode, ComponentNode, DocumentBlock, Finding, InlineNode, IRBlock, IRSection, JsonObject, MdastNode, NarrationNode, RichTextNode, SourcePos, TeachingDocument, TextStyle, VisualState } from '@lincyaw/kernel'
3
+ import { resolve } from 'node:path'
4
4
 
5
5
  const pointerKey = (id: string) => id.replaceAll('~', '~0').replaceAll('/', '~1')
6
6
  const source = (entry: string, pointer: string): SourcePos => ({ file: entry, line: 1, format: 'json', pointer })
@@ -30,7 +30,6 @@ export function lowerDocument(doc: TeachingDocument, entry: string, deckDir: str
30
30
  const stateIndex = definition?.states.findIndex(state => state.id === visual?.state) ?? -1
31
31
  const local = stateIndex < 0 ? 0 : definition!.states[stateIndex]!.legacyIndex ?? stateIndex
32
32
  const parameters = { ...block.type === 'component' ? block.parameters : {}, ...visual?.parameters }
33
- if (definition && isMotionScene(definition)) delete parameters.scene
34
33
  return { visible: visual?.visible ?? false, localStep: block.type === 'code' ? stepIndex : local, ...visual?.state !== undefined ? { state: visual.state } : {}, ...block.type === 'component' || visual?.parameters ? { parameters } : {} }
35
34
  })
36
35
  const visible = stepStates.flatMap((state, at) => state.visible ? [at] : [])
@@ -68,8 +67,8 @@ export function lowerDocument(doc: TeachingDocument, entry: string, deckDir: str
68
67
  const definition = doc.definitions[block.definitionId]!
69
68
  const implementation = definition.implementation
70
69
  const data = definition.data ?? {}
71
- const plugin = typeof data.plugin === 'string' ? data.plugin : implementation.type === 'plugin' ? implementation.plugin : isMotionScene(definition) ? 'presmium.motion' : 'deck'
72
- const name = typeof data.name === 'string' ? data.name : implementation.type === 'plugin' ? implementation.name : isMotionScene(definition) ? 'PmScene' : `presmium-definition:${definition.id}`
70
+ const plugin = typeof data.plugin === 'string' ? data.plugin : implementation.type === 'plugin' ? implementation.plugin : 'deck'
71
+ const name = typeof data.name === 'string' ? data.name : implementation.type === 'plugin' ? implementation.name : `presmium-definition:${definition.id}`
73
72
  const node: ComponentNode = { type: 'component', plugin, name, props: { ...block.parameters }, ...block.children ? { children: block.children.map(child) } : {} }
74
73
  if (Array.isArray(data.durations) && data.durations.every(value => typeof value === 'number')) node.durations = data.durations
75
74
  if (isRecord(data.fallback) && typeof data.fallback.type === 'string') node.fallback = structuredClone(data.fallback) as MdastNode
@@ -79,14 +78,7 @@ export function lowerDocument(doc: TeachingDocument, entry: string, deckDir: str
79
78
  if (implementation.type === 'file') {
80
79
  const file = resolve(deckDir, implementation.path)
81
80
  watch(file)
82
- if (isMotionScene(definition)) {
83
- if (implementation.exportName && implementation.exportName !== 'default') report({ checkId: 'presmium.document', severity: 'error', message: 'Motion scene files currently require their default export.', source: where })
84
- const path = relative(deckDir, file).split(sep).join('/')
85
- const scene = /^scenes\/([\w-]+(?:\/[\w-]+)*)\.(?:ts|js|mjs)$/.exec(path)?.[1]
86
- if (scene) node.props.scene = scene
87
- else report({ checkId: 'presmium.document', severity: 'error', message: 'A motion scene implementation must be a supported file below scenes/.', source: where })
88
- }
89
- node.definition = { file, language: typeof data.language === 'string' ? data.language : /\.[cm]?tsx?$/.test(file) ? 'typescript' : 'javascript', ...implementation.exportName !== undefined ? { exportName: implementation.exportName } : {} }
81
+ node.definition = { file, kind: definition.kind, language: typeof data.language === 'string' ? data.language : /\.[cm]?tsx?$/.test(file) ? 'typescript' : 'javascript', ...implementation.exportName !== undefined ? { exportName: implementation.exportName } : {} }
90
82
  }
91
83
  if (implementation.type === 'module') report({ checkId: 'presmium.document', severity: 'error', message: 'Module component implementations are not available in the current document runtime; use a project file or a registered plugin component.', source: where })
92
84
  return node
@@ -117,10 +109,6 @@ export function lowerDocument(doc: TeachingDocument, entry: string, deckDir: str
117
109
  })
118
110
  }
119
111
 
120
- function isMotionScene(definition: Definition): boolean {
121
- return definition.kind === 'scene' && definition.implementation.type === 'file' && (!definition.data?.plugin || definition.data.plugin === 'presmium.motion') && (!definition.data?.name || definition.data.name === 'PmScene')
122
- }
123
-
124
112
  function styled(node: MdastNode, style: TextStyle | undefined): MdastNode {
125
113
  if (!style) return node
126
114
  const properties: Record<string, string> = {}
package/src/import.ts ADDED
@@ -0,0 +1,210 @@
1
+ // `presmium import`: a folder of Markdown notes (or one note) to documents, one `lecture.json` per note.
2
+ //
3
+ // `a/b/note.md` becomes `<out>/a/b/note/lecture.json`. Wikilinks resolve as note-taking apps resolve them: by path,
4
+ // then by file name or alias (case-insensitive), the nearest note winning when several share a name; a folder's
5
+ // `index` or `README` note also answers to the folder's name. A local file a note links to is copied into its
6
+ // document's `attachments/`, since a document publishes only files inside the workspace; an excluded folder (`raw`,
7
+ // say) is neither imported nor copied from.
8
+ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
9
+ import { basename, dirname, extname, join, posix, relative, resolve, sep } from 'node:path'
10
+ import type { MdastNode } from '@lincyaw/kernel'
11
+ import { DOCUMENT_ENTRY } from '@lincyaw/kernel'
12
+ import { headingSlug, markdownDocument, noteTitle, splitFrontmatter } from './markdown.ts'
13
+
14
+ export interface ImportOptions {
15
+ out: string
16
+ /** Names (with `*`) of folders and files to leave out, matched against each part of a path. */
17
+ exclude?: string[]
18
+ lang?: string
19
+ /** The note's folder at this depth becomes the document's first tag, by which the site's sidebar groups documents. */
20
+ group?: number
21
+ /** Retains the exact source beside the editable converted document. */
22
+ preserveOriginal?: boolean
23
+ }
24
+
25
+ export interface ImportReport {
26
+ /** The written documents' folders, relative to `out`. */
27
+ documents: string[]
28
+ files: number
29
+ unresolved: { note: string, link: string }[]
30
+ warnings?: number
31
+ }
32
+
33
+ interface Note { file: string, path: string, dir: string, title: string, aliases: string[], text: string, assets?: Map<string, Uint8Array>, warnings?: number, tree?: MdastNode }
34
+
35
+ const MARKDOWN = new Set(['.md', '.markdown'])
36
+ const SKIPPED = new Set(['node_modules'])
37
+ const RESERVED = new Set(['dist', 'templates', 'node_modules'])
38
+ const FOLDER_NOTES = new Set(['index', 'readme'])
39
+ const ATTACHMENTS = 'attachments'
40
+
41
+ const glob = (pattern: string) => new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`, 'i')
42
+ const toPosix = (path: string) => path.split(sep).join('/')
43
+ const key = (target: string) => target.trim().replace(/^\/+/, '').replace(/\.(?:md|markdown|docx)$/i, '').toLowerCase()
44
+ /** A document folder's part: letters, digits, `.`, `_` and `-`, not starting with `.`. */
45
+ const part = (name: string) => name.replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^[.-]+/, '') || 'note'
46
+
47
+ function discover(input: string, options: ImportOptions, extensions: ReadonlySet<string>) {
48
+ const source = resolve(input)
49
+ const out = resolve(options.out)
50
+ const excluded = (options.exclude ?? []).map(glob)
51
+ const isExcluded = (path: string) => path.split('/').some(name => excluded.some(pattern => pattern.test(name)))
52
+ const single = statSync(source).isFile()
53
+ const root = single ? dirname(source) : source
54
+
55
+ const files: string[] = []
56
+ const seen = new Set<string>()
57
+ const walk = (dir: string) => {
58
+ const real = realpathSync(dir)
59
+ if (existsSync(join(dir, DOCUMENT_ENTRY)) || (dir !== root && resolve(dir) === out) || seen.has(real)) return
60
+ seen.add(real)
61
+ for (const name of readdirSync(dir).sort()) {
62
+ const file = join(dir, name)
63
+ if (name.startsWith('.') || SKIPPED.has(name) || isExcluded(toPosix(relative(root, file)))) continue
64
+ const stat = statSync(file, { throwIfNoEntry: false })
65
+ if (stat?.isDirectory()) walk(file)
66
+ else if (stat?.isFile() && extensions.has(extname(name).toLowerCase())) files.push(file)
67
+ }
68
+ }
69
+ if (single) { if (extensions.has(extname(source).toLowerCase())) files.push(source) }
70
+ else walk(source)
71
+
72
+ return { root, out, files, isExcluded }
73
+ }
74
+
75
+ export function importMarkdown(input: string, options: ImportOptions): ImportReport {
76
+ const found = discover(input, options, MARKDOWN)
77
+ return writeNotes(found, options, found.files.map(file => ({ file, text: new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(file)) })))
78
+ }
79
+
80
+ /** One editable document per Markdown or Word source, with shared link and attachment resolution. */
81
+ export async function importDocuments(input: string, options: ImportOptions): Promise<ImportReport> {
82
+ const found = discover(input, options, new Set([...MARKDOWN, '.docx']))
83
+ const sources: { file: string, text: string, assets?: Map<string, Uint8Array>, warnings?: number, tree?: MdastNode }[] = []
84
+ for (const file of found.files) sources.push(extname(file).toLowerCase() === '.docx'
85
+ ? { file, ...await (await import('./word.ts')).wordMarkdown(readFileSync(file)) }
86
+ : { file, text: new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(file)) })
87
+ return writeNotes(found, options, sources)
88
+ }
89
+
90
+ function writeNotes({ root, out, isExcluded }: ReturnType<typeof discover>, options: ImportOptions, sources: { file: string, text: string, assets?: Map<string, Uint8Array>, warnings?: number, tree?: MdastNode }[]): ImportReport {
91
+
92
+ const taken = new Set<string>()
93
+ const notes: Note[] = sources.map(({ file, text, assets, warnings, tree }) => {
94
+ const path = toPosix(relative(root, file))
95
+ const parts = path.replace(/\.(?:md|markdown|docx)$/i, '').split('/').map(part)
96
+ if (RESERVED.has(parts[0]!)) parts[0] = `${parts[0]}-notes`
97
+ let dir = parts.join('/')
98
+ for (let n = 2; taken.has(dir.toLowerCase()); n++) dir = `${parts.join('/')}-${n}`
99
+ taken.add(dir.toLowerCase())
100
+ return { file, path, dir, text, assets, warnings, tree, title: noteTitle(text) ?? basename(file, extname(file)), aliases: splitFrontmatter(text).frontmatter.aliases }
101
+ })
102
+
103
+ const pathKey = (path: string) => posix.normalize(path).replace(/^\/+/, '').toLowerCase()
104
+ const byPath = new Map(notes.map(note => [pathKey(note.path), note]))
105
+ const byStem = new Map<string, Note[]>()
106
+ for (const note of notes) { const stem = key(note.path); byStem.set(stem, [...byStem.get(stem) ?? [], note]) }
107
+ const pathNote = (path: string) => {
108
+ const exact = byPath.get(pathKey(path))
109
+ const candidates = byStem.get(key(posix.normalize(path))) ?? []
110
+ return exact ?? (!/\.(?:md|markdown|docx)$/i.test(path) && candidates.length === 1 ? candidates[0] : undefined)
111
+ }
112
+ const byName = new Map<string, Note[]>()
113
+ const register = (name: string, note: Note) => {
114
+ const k = key(name)
115
+ if (k && !byName.get(k)?.includes(note)) byName.set(k, [...byName.get(k) ?? [], note])
116
+ }
117
+ for (const note of notes) {
118
+ const stem = posix.basename(note.path).replace(/\.(?:md|markdown|docx)$/i, '')
119
+ register(stem, note)
120
+ note.aliases.forEach(alias => register(alias, note))
121
+ if (FOLDER_NOTES.has(stem.toLowerCase()) && posix.dirname(note.path) !== '.') register(posix.basename(posix.dirname(note.path)), note)
122
+ }
123
+ /** The note nearest to `from` among `candidates`: the one sharing the longest folder path, if only one does. */
124
+ const nearest = (from: Note, candidates: Note[]) => {
125
+ const shared = (note: Note) => {
126
+ const a = posix.dirname(from.path).split('/'), b = posix.dirname(note.path).split('/')
127
+ let n = 0
128
+ while (n < a.length && a[n] === b[n]) n++
129
+ return n
130
+ }
131
+ const best = Math.max(...candidates.map(shared))
132
+ const winners = candidates.filter(note => shared(note) === best)
133
+ return winners.length === 1 ? winners[0] : undefined
134
+ }
135
+ const href = (from: Note, to: Note, fragment?: string) => {
136
+ const path = posix.relative(from.dir, to.dir)
137
+ return `${path ? `${path}/` : ''}${DOCUMENT_ENTRY}${fragment ? `#${headingSlug(fragment)}` : ''}`
138
+ }
139
+
140
+ const report: ImportReport = { documents: [], files: 0, unresolved: [] }
141
+ const copied = new Map<string, string | Uint8Array>()
142
+ for (const note of notes) {
143
+ const docDir = join(out, note.dir)
144
+ const names = new Map<string, string>()
145
+ /** A file inside the imported folder to its copy in the document's attachments; undefined for anything else. */
146
+ const attach = (url: string) => {
147
+ const embedded = note.assets?.get(url)
148
+ if (embedded) {
149
+ const copy = `${ATTACHMENTS}/${basename(url)}`
150
+ copied.set(join(docDir, copy), embedded)
151
+ return copy
152
+ }
153
+ const [path = '', ...fragment] = url.split('#')
154
+ let name = path
155
+ try {
156
+ name = decodeURIComponent(path)
157
+ } catch {
158
+ }
159
+ const file = resolve(dirname(note.file), name)
160
+ const rel = toPosix(relative(root, file))
161
+ if (!name || rel.startsWith('../') || isExcluded(rel) || !statSync(file, { throwIfNoEntry: false })?.isFile()) return undefined
162
+ const target = byPath.get(pathKey(rel))
163
+ if (target) return href(note, target, fragment.length ? fragment.join('#') : undefined)
164
+ let copy = names.get(file)
165
+ if (!copy) {
166
+ const base = basename(file)
167
+ copy = [...names.values()].includes(`${ATTACHMENTS}/${base}`) ? `${ATTACHMENTS}/${names.size}-${base}` : `${ATTACHMENTS}/${base}`
168
+ names.set(file, copy)
169
+ }
170
+ copied.set(join(docDir, copy), file)
171
+ return `${encodeURI(copy)}${fragment.length ? `#${fragment.join('#')}` : ''}`
172
+ }
173
+ const { document, unresolved } = markdownDocument(note.text, {
174
+ id: note.dir.replace(/\//g, '--'),
175
+ title: note.title,
176
+ tree: note.tree,
177
+ lang: options.lang,
178
+ links: {
179
+ page: (target, fragment) => {
180
+ const direct = pathNote(posix.join(posix.dirname(note.path), target)) ?? pathNote(target)
181
+ const candidates = byName.get(key(target)) ?? []
182
+ const found = direct ?? (candidates.length === 1 ? candidates[0] : candidates.length > 1 ? nearest(note, candidates) : undefined)
183
+ return found && href(note, found, fragment)
184
+ },
185
+ url: attach,
186
+ image: attach,
187
+ },
188
+ })
189
+ const folder = options.group ? posix.dirname(note.path).split('/').slice(0, options.group).at(-1) : undefined
190
+ if (folder && folder !== '.') document.metadata.tags = [folder, ...(document.metadata.tags ?? []).filter(tag => tag !== folder)]
191
+ mkdirSync(docDir, { recursive: true })
192
+ writeFileSync(join(docDir, DOCUMENT_ENTRY), `${JSON.stringify(document, null, 2)}\n`)
193
+ report.documents.push(note.dir)
194
+ report.unresolved.push(...unresolved.map(link => ({ note: note.path, link })))
195
+ if (note.warnings) report.warnings = (report.warnings ?? 0) + note.warnings
196
+ if (options.preserveOriginal) copied.set(join(docDir, 'originals', basename(note.file)), note.file)
197
+ }
198
+ for (const [copy, file] of copied) {
199
+ mkdirSync(dirname(copy), { recursive: true })
200
+ if (typeof file !== 'string') writeFileSync(copy, file)
201
+ else if (!existsSync(copy) || statSync(copy).mtimeMs < statSync(file).mtimeMs || statSync(copy).size !== statSync(file).size) copyFileSync(file, copy)
202
+ }
203
+ report.files = copied.size
204
+ return report
205
+ }
206
+
207
+ /** The `documents` patterns that cover these folders: one per depth, as workspace patterns do not cross folders. */
208
+ export function documentPatterns(dirs: string[]): string[] {
209
+ return [...new Set(dirs.map(dir => dir.split('/').length))].sort((a, b) => a - b).map(depth => `${'*/'.repeat(depth)}${DOCUMENT_ENTRY}`)
210
+ }
package/src/index.ts CHANGED
@@ -1,4 +1,8 @@
1
1
  export { directoryAsset, fileHash, publishesDirectory } from './assets.ts'
2
+ export { documentPatterns, importDocuments, importMarkdown } from './import.ts'
3
+ export type { ImportOptions, ImportReport } from './import.ts'
4
+ export { headingSlug, markdownDocument, noteTitle, splitFrontmatter } from './markdown.ts'
5
+ export type { Frontmatter, ImportedMarkdown, MarkdownLinks } from './markdown.ts'
2
6
  export { availableRenderers, build } from './build.ts'
3
7
  export type { BuildOptions, BuildReport } from './build.ts'
4
8
  export { buildSummary, buildToDist, checkContext, runBlock } from './compilation-actions.ts'
@@ -6,8 +10,6 @@ export { Compiler, DECK_ENTRY, resolveEntry, sortFindings, workspacePlugins } fr
6
10
  export type { Compilation, CompileOptions, CompilerOptions, DocumentNodeServices } from './compiler.ts'
7
11
  export { dev } from './dev.ts'
8
12
  export type { DevOptions, DevServers } from './dev.ts'
9
- export { BUILTIN_DIRECTIVE_INFO, COMMON_DIRECTIVE_OPTIONS, RUN_OPTION } from './directives.ts'
10
- export type { DirectiveInfo, DirectiveOptionInfo } from './directives.ts'
11
13
  export type { RunStats } from './execute.ts'
12
14
  export type { GitRead } from './inputs.ts'
13
15
  export { pluginLogger } from './logging.ts'
@@ -26,5 +28,6 @@ export { frontmatterLine, lineContaining } from './source-lines.ts'
26
28
  export { compileTranslations, documentDigest } from './translations.ts'
27
29
  export type { CompiledTranslation } from './translations.ts'
28
30
  export { viewFor } from './views.ts'
31
+ export { findWorkspaceRoot } from './workspace.ts'
29
32
  export { operatorDir, WORKSPACE_CONFIG, workspaceSettings } from './workspace-settings.ts'
30
33
  export type { OperatorSettings } from './workspace-settings.ts'
@@ -0,0 +1,336 @@
1
+ // One Markdown note to one document (`presmium import`). Pure: the caller resolves links and copies files.
2
+ //
3
+ // Each level-1 or level-2 heading starts a page (the first page holds what comes before it, under the note's title);
4
+ // every page has one step that shows all its blocks. Paragraphs, headings, lists, quotes, code, math and tables become
5
+ // rich text; a Mermaid diagram becomes a code block of its own, which is what draws it; a paragraph holding only an
6
+ // image becomes an image block. What has no rich-text node (raw HTML, footnotes, rules, callouts) is kept as an mdast
7
+ // extension that the viewer renders. `[[target]]` and `[[target|label]]` wikilinks, relative links and images go through
8
+ // the caller's `links`. Node ids come from the content, so importing an unchanged paragraph again keeps its id.
9
+ import { fromMarkdown } from 'mdast-util-from-markdown'
10
+ import { gfmFromMarkdown } from 'mdast-util-gfm'
11
+ import { mathFromMarkdown } from 'mdast-util-math'
12
+ import { gfm } from 'micromark-extension-gfm'
13
+ import { math } from 'micromark-extension-math'
14
+ import { parse as parseYaml } from 'yaml'
15
+ import type { Asset, DocumentBlock, InlineNode, MdastNode, RichTextNode, Section, Step, TeachingDocument, TextMark } from '@lincyaw/kernel'
16
+
17
+ export interface Frontmatter {
18
+ title?: string
19
+ description?: string
20
+ lang?: string
21
+ tags: string[]
22
+ aliases: string[]
23
+ }
24
+
25
+ export interface MarkdownLinks {
26
+ /** A wikilink's target (without `#fragment`) to the href of the document it names; undefined when there is none. */
27
+ page(target: string, fragment: string | undefined): string | undefined
28
+ /** A relative URL of a link to its new href; undefined when it leads nowhere that is published. */
29
+ url(url: string): string | undefined
30
+ /** A relative URL of an image to the location of its copy, relative to the document. */
31
+ image(url: string): string | undefined
32
+ }
33
+
34
+ export interface ImportedMarkdown {
35
+ document: TeachingDocument
36
+ /** Wikilinks and relative links that `links` could not resolve, as written. */
37
+ unresolved: string[]
38
+ }
39
+
40
+ const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/
41
+ /** Stands in for the `|` of `[[target|label]]` while parsing, so a GFM table does not split the cell at it. */
42
+ const LABEL = '\uE000'
43
+ const WIKILINK = new RegExp(`\\[\\[([^\\]|${LABEL}\\n]+)(?:[|${LABEL}]([^\\]\\n]+))?\\]\\]`, 'g')
44
+ const HIGHLIGHT = /==(?=\S)([^=\n]*\S)==/g
45
+ const CALLOUT = /^\[!([A-Za-z]+)\][+-]?[ \t]*/
46
+ const SCHEME = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i
47
+ const MARKS: Record<string, TextMark['type']> = { strong: 'bold', emphasis: 'italic', delete: 'strike' }
48
+ const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu
49
+ const LETTER = /\p{L}/gu
50
+
51
+ export function splitFrontmatter(source: string): { frontmatter: Frontmatter, body: string } {
52
+ const match = FRONTMATTER.exec(source)
53
+ let data: unknown
54
+ if (match) {
55
+ try {
56
+ data = parseYaml(match[1]!)
57
+ } catch {
58
+ }
59
+ }
60
+ const record = data !== null && typeof data === 'object' && !Array.isArray(data) ? data as Record<string, unknown> : {}
61
+ const text = (key: string) => (typeof record[key] === 'string' && (record[key] as string).trim() ? (record[key] as string).trim() : undefined)
62
+ const list = (key: string) => {
63
+ const value = record[key]
64
+ return (Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [])
65
+ .flatMap(item => (typeof item === 'string' || typeof item === 'number' ? [String(item).trim()] : [])).filter(Boolean)
66
+ }
67
+ return {
68
+ frontmatter: { title: text('title'), description: text('description'), lang: text('lang'), tags: list('tags'), aliases: list('aliases') },
69
+ body: match ? source.slice(match[0].length) : source,
70
+ }
71
+ }
72
+
73
+ /** The title of a note: its frontmatter title, else its first level-1 heading. */
74
+ export function noteTitle(source: string): string | undefined {
75
+ const { frontmatter, body } = splitFrontmatter(source)
76
+ return frontmatter.title ?? /^#[ \t]+(.+?)[ \t#]*$/m.exec(body)?.[1]?.trim()
77
+ }
78
+
79
+ /** The anchor of a heading, as GitHub writes it: lower case, punctuation dropped, spaces to hyphens. */
80
+ export function headingSlug(text: string): string {
81
+ return text.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/\s/g, '-')
82
+ }
83
+
84
+ function guessLang(text: string): string {
85
+ const letters = text.match(LETTER)?.length ?? 0
86
+ return letters > 0 && (text.match(CJK)?.length ?? 0) / letters > 0.3 ? 'zh-CN' : 'en'
87
+ }
88
+
89
+ function plain(node: MdastNode): string {
90
+ if (typeof node.value === 'string') return node.value
91
+ return (node.children ?? []).map(plain).join('')
92
+ }
93
+
94
+ function hash(text: string): string {
95
+ let h = 0x811c9dc5
96
+ for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193)
97
+ return (h >>> 0).toString(36)
98
+ }
99
+
100
+ function withoutPositions(node: MdastNode): unknown {
101
+ const { position: _position, children, ...rest } = node
102
+ return children ? { ...rest, children: children.map(withoutPositions) } : rest
103
+ }
104
+
105
+ function restoreLabels(node: MdastNode): void {
106
+ if (typeof node.value === 'string') node.value = node.value.replaceAll(LABEL, '|')
107
+ node.children?.forEach(restoreLabels)
108
+ }
109
+
110
+ export function markdownDocument(source: string, options: { id: string, title: string, lang?: string, tree?: MdastNode, links: MarkdownLinks }): ImportedMarkdown {
111
+ const { frontmatter, body } = splitFrontmatter(source)
112
+ const protectedBody = body.replace(/\[\[([^\]|\n]+)\|([^\]\n]+)\]\]/g, (_, target: string, label: string) => `[[${target}${LABEL}${label}]]`)
113
+ const root = options.tree ? structuredClone(options.tree) : fromMarkdown(protectedBody, { extensions: [gfm(), math()], mdastExtensions: [gfmFromMarkdown(), mathFromMarkdown()] }) as unknown as MdastNode
114
+ const unresolved: string[] = []
115
+ const definitions = new Map<string, string>()
116
+ const collect = (node: MdastNode) => {
117
+ if (node.type === 'definition') definitions.set(String(node.identifier).toLowerCase(), String(node.url))
118
+ node.children?.forEach(collect)
119
+ }
120
+ collect(root)
121
+
122
+ // Links are rewritten in the mdast first, so callouts and other extensions carry the same hrefs as rich text.
123
+ const relink = (node: MdastNode): MdastNode[] => {
124
+ if (node.type === 'text' && typeof node.value === 'string' && node.value.includes('[[')) return wikilinks(node.value)
125
+ if ((node.type === 'link' || node.type === 'definition') && typeof node.url === 'string' && !SCHEME.test(node.url)) {
126
+ const href = options.links.url(node.url)
127
+ if (href === undefined) {
128
+ unresolved.push(node.url)
129
+ if (node.type === 'link') return (node.children ?? []).flatMap(relink)
130
+ }
131
+ node.url = href ?? node.url
132
+ }
133
+ if (node.type === 'imageReference') {
134
+ const url = definitions.get(String(node.identifier).toLowerCase())
135
+ if (url !== undefined) return relink({ type: 'image', url, alt: node.alt, title: node.title })
136
+ }
137
+ if (node.type === 'image' && typeof node.url === 'string') {
138
+ const location = /^(?:https?:|\/\/)/i.test(node.url) ? node.url : options.links.image(node.url)
139
+ if (location === undefined) { unresolved.push(node.url); return [{ type: 'text', value: String(node.alt ?? '') }] }
140
+ node.url = location
141
+ }
142
+ if (node.type === 'linkReference') {
143
+ const url = definitions.get(String(node.identifier).toLowerCase())
144
+ if (url !== undefined) return relink({ type: 'link', url, children: node.children ?? [] })
145
+ }
146
+ if (node.children) node.children = node.children.flatMap(relink)
147
+ return [node]
148
+ }
149
+ const wikilinks = (value: string): MdastNode[] => {
150
+ const out: MdastNode[] = []
151
+ let cursor = 0
152
+ for (const match of value.matchAll(WIKILINK)) {
153
+ if (match.index > cursor) out.push({ type: 'text', value: value.slice(cursor, match.index) })
154
+ const written = match[1]!.trim()
155
+ const [target = '', ...fragment] = written.split('#')
156
+ const label = (match[2] ?? written).trim()
157
+ const href = options.links.page(target.trim(), fragment.length ? fragment.join('#') : undefined)
158
+ if (href === undefined) unresolved.push(`[[${written}]]`)
159
+ out.push(href === undefined ? { type: 'text', value: label } : { type: 'link', url: href, children: [{ type: 'text', value: label }] })
160
+ cursor = match.index + match[0].length
161
+ }
162
+ if (cursor < value.length) out.push({ type: 'text', value: value.slice(cursor) })
163
+ return out
164
+ }
165
+ root.children = (root.children ?? []).flatMap(relink)
166
+ restoreLabels(root)
167
+
168
+ const used = new Set<string>([options.id])
169
+ const unique = (base: string) => {
170
+ let id = base.slice(0, 180) || 'node'
171
+ for (let n = 2; used.has(id); n++) id = `${base.slice(0, 180)}-${n}`
172
+ used.add(id)
173
+ return id
174
+ }
175
+ const idOf = (prefix: string, node: MdastNode) => unique(`${prefix}-${hash(JSON.stringify(withoutPositions(node)))}`)
176
+ const extension = (node: MdastNode): RichTextNode => {
177
+ const text = plain(node).trim()
178
+ return { id: idOf(node.type, node), type: 'extension', kind: 'presmium.mdast', schemaVersion: 1, data: { node: withoutPositions(node) as never },
179
+ fallback: text ? [{ id: idOf('fallback', node), type: 'paragraph', children: [{ type: 'text', text }] }] : [] }
180
+ }
181
+
182
+ const inline = (nodes: MdastNode[], marks: TextMark[] = []): InlineNode[] => nodes.flatMap((node): InlineNode[] => {
183
+ const styled = (text: string, extra: TextMark[] = []): InlineNode => ({ type: 'text', text, ...marks.length + extra.length ? { marks: [...marks, ...extra] } : {} })
184
+ if (node.type === 'text') {
185
+ const value = String(node.value ?? '')
186
+ if (!value.includes('==')) return value ? [styled(value)] : []
187
+ const out: InlineNode[] = []
188
+ let cursor = 0
189
+ for (const match of value.matchAll(HIGHLIGHT)) {
190
+ if (match.index > cursor) out.push(styled(value.slice(cursor, match.index)))
191
+ out.push(styled(match[1]!, [{ type: 'background', value: 'warn' }]))
192
+ cursor = match.index + match[0].length
193
+ }
194
+ if (cursor < value.length) out.push(styled(value.slice(cursor)))
195
+ return out
196
+ }
197
+ if (node.type === 'break') return [{ type: 'break' }]
198
+ if (node.type === 'inlineMath') return [{ type: 'math', value: String(node.value ?? '') }]
199
+ if (node.type === 'inlineCode') return [styled(String(node.value ?? ''), [{ type: 'code' }])]
200
+ if (MARKS[node.type]) return inline(node.children ?? [], [...marks, { type: MARKS[node.type]! } as TextMark])
201
+ if (node.type === 'link') return [{ type: 'link', href: String(node.url), children: inline(node.children ?? [], marks) }]
202
+ if (node.type === 'image' && typeof node.url === 'string') {
203
+ return [{ type: 'extension', kind: 'presmium.mdast', schemaVersion: 1, data: { node: withoutPositions(node) as never }, fallback: String(node.alt ?? '') }]
204
+ }
205
+ return [{ type: 'extension', kind: 'presmium.mdast', schemaVersion: 1, data: { node: withoutPositions(node) as never }, fallback: plain(node) }]
206
+ })
207
+
208
+ const rich = (node: MdastNode): RichTextNode[] => {
209
+ const children = node.children ?? []
210
+ switch (node.type) {
211
+ case 'paragraph': {
212
+ const content = inline(children)
213
+ return content.length ? [{ id: idOf('p', node), type: 'paragraph', children: content }] : []
214
+ }
215
+ case 'heading':
216
+ return [{ id: unique(headingSlug(plain(node)) || `h-${hash(plain(node))}`), type: 'heading', level: Math.min(6, Math.max(1, Number(node.depth))) as 1, children: inline(children) }]
217
+ case 'blockquote': {
218
+ const callout = calloutOf(node)
219
+ return callout ? [extension(callout)] : [{ id: idOf('quote', node), type: 'blockquote', children: children.flatMap(rich) }]
220
+ }
221
+ case 'list':
222
+ return [{ id: idOf('list', node), type: 'list', ordered: Boolean(node.ordered), ...Number(node.start) >= 1 ? { start: Number(node.start) } : {},
223
+ children: children.map(item => ({ id: idOf('item', item), type: 'listItem', ...typeof item.checked === 'boolean' ? { checked: item.checked } : {}, children: (item.children ?? []).flatMap(rich) })) }]
224
+ case 'code':
225
+ return [{ id: idOf('code', node), type: 'code', language: String(node.lang ?? ''), value: String(node.value ?? '') }]
226
+ case 'math':
227
+ return [{ id: idOf('math', node), type: 'math', value: String(node.value ?? '') }]
228
+ case 'table': {
229
+ const align = Array.isArray(node.align) ? node.align as (string | null)[] : []
230
+ return [{ id: idOf('table', node), type: 'table', headerRows: node.headerRows === 0 ? 0 : 1, children: children.map(row => ({ id: idOf('row', row), type: 'tableRow',
231
+ children: (row.children ?? []).map((cell, c) => ({ id: idOf('cell', cell), type: 'tableCell', children: inline(cell.children ?? []),
232
+ ...align[c] ? { style: { alignment: align[c] as 'left' } } : {} })) })) }]
233
+ }
234
+ case 'definition':
235
+ return []
236
+ default:
237
+ return [extension(node)]
238
+ }
239
+ }
240
+
241
+ // Pages: a level-1 or level-2 heading starts one. The note's own title heading opens the first page and is not repeated.
242
+ const nodes = root.children ?? []
243
+ const title = frontmatter.title ?? (nodes[0]?.type === 'heading' && nodes[0].depth === 1 ? plain(nodes[0]).trim() : undefined) ?? options.title
244
+ const pages: { title: string, level: number, nodes: MdastNode[] }[] = [{ title, level: 1, nodes: [] }]
245
+ nodes.forEach((node, i) => {
246
+ const opensPage = node.type === 'heading' && Number(node.depth) <= 2
247
+ if (opensPage && i === 0 && node.depth === 1 && plain(node).trim() === title) return
248
+ if (opensPage) pages.push({ title: plain(node).trim() || title, level: Number(node.depth), nodes: [] })
249
+ else pages.at(-1)!.nodes.push(node)
250
+ })
251
+ if (pages.length > 1 && pages[0]!.nodes.length === 0 && pages[1]!.level === 1) pages.shift()
252
+
253
+ const sections: Record<string, Section> = {}, blocks: Record<string, DocumentBlock> = {}, steps: Record<string, Step> = {}, assets: Record<string, Asset> = {}
254
+ const sectionOrder: string[] = []
255
+ for (const page of pages) {
256
+ const sectionId = unique(headingSlug(page.title) || `page-${hash(page.title)}`)
257
+ const children: string[] = []
258
+ let text: RichTextNode[] = []
259
+ const flush = () => {
260
+ if (!text.length) return
261
+ const id = unique(`${sectionId}--text-${children.length}`)
262
+ blocks[id] = { id, type: 'text', content: text }
263
+ children.push(id)
264
+ text = []
265
+ }
266
+ for (const node of page.nodes) {
267
+ const image = node.type === 'paragraph' ? soleImage(node) : undefined
268
+ const location = image && typeof image.url === 'string' ? image.url : undefined
269
+ if (node.type === 'code' && (node.lang === 'mermaid' || node.lang === 'mmd')) {
270
+ flush()
271
+ const id = unique(`${sectionId}--diagram-${children.length}`)
272
+ blocks[id] = { id, type: 'code', language: 'mermaid', value: String(node.value ?? '') }
273
+ children.push(id)
274
+ } else if (image && location) {
275
+ flush()
276
+ const id = unique(`${sectionId}--image-${children.length}`), assetId = unique(`asset-${hash(location)}`)
277
+ assets[assetId] = { id: assetId, kind: 'image', location, ...image.title ? { title: String(image.title) } : {} }
278
+ blocks[id] = { id, type: 'image', assetId, alt: String(image.alt ?? '') }
279
+ children.push(id)
280
+ } else {
281
+ if (image && !location && typeof image.url === 'string') unresolved.push(image.url)
282
+ text.push(...rich(node))
283
+ }
284
+ }
285
+ flush()
286
+ const stepId = unique(`${sectionId}--step`)
287
+ sections[sectionId] = { id: sectionId, title: page.title, level: Math.min(2, page.level) as 1, children, stepOrder: [stepId], layout: { type: 'stack' } }
288
+ steps[stepId] = { id: stepId, sectionId, visuals: children.map(blockId => ({ blockId, visible: true })), narrationIds: [] }
289
+ sectionOrder.push(sectionId)
290
+ }
291
+
292
+ return {
293
+ document: {
294
+ schemaVersion: 1,
295
+ id: options.id,
296
+ metadata: {
297
+ title,
298
+ lang: frontmatter.lang ?? options.lang ?? guessLang(body),
299
+ ...frontmatter.description ? { description: frontmatter.description } : {},
300
+ ...frontmatter.tags.length ? { tags: frontmatter.tags } : {},
301
+ plugins: [],
302
+ renderers: { web: {} },
303
+ },
304
+ sectionOrder, sections, blocks, steps, narrations: {}, assets, definitions: {},
305
+ production: { defaults: {}, stepOverrides: {}, mediaClips: [] },
306
+ } as TeachingDocument,
307
+ unresolved: [...new Set(unresolved)],
308
+ }
309
+ }
310
+
311
+ function soleImage(paragraph: MdastNode): MdastNode | undefined {
312
+ const content = (paragraph.children ?? []).filter(child => !(child.type === 'text' && !String(child.value ?? '').trim()))
313
+ return content.length === 1 && content[0]!.type === 'image' ? content[0] : undefined
314
+ }
315
+
316
+ /** `> [!note] Title` (as GitHub and Obsidian write callouts) as a MyST admonition, which the viewer draws as one. */
317
+ function calloutOf(quote: MdastNode): MdastNode | undefined {
318
+ const first = quote.children?.[0]
319
+ const lead = first?.type === 'paragraph' ? first.children?.[0] : undefined
320
+ const match = lead?.type === 'text' ? CALLOUT.exec(String(lead.value ?? '')) : null
321
+ if (!first || !lead || !match) return undefined
322
+ const rest = String(lead.value).slice(match[0].length)
323
+ const breakAt = rest.indexOf('\n')
324
+ const titleText = (breakAt < 0 ? rest : rest.slice(0, breakAt)).trim()
325
+ const bodyLead = breakAt < 0 ? '' : rest.slice(breakAt + 1)
326
+ const inlineRest = [...bodyLead ? [{ type: 'text', value: bodyLead }] : [], ...(first.children ?? []).slice(1)]
327
+ const kind = match[1]!.toLowerCase()
328
+ return {
329
+ type: 'admonition', kind,
330
+ children: [
331
+ { type: 'admonitionTitle', children: [{ type: 'text', value: titleText || kind.charAt(0).toUpperCase() + kind.slice(1) }] },
332
+ ...inlineRest.length ? [{ type: 'paragraph', children: inlineRest }] : [],
333
+ ...(quote.children ?? []).slice(1),
334
+ ],
335
+ }
336
+ }
package/src/plugins.ts CHANGED
@@ -3,10 +3,10 @@ import { readdir, readFile } from 'node:fs/promises'
3
3
  import { dirname, isAbsolute, join, resolve } from 'node:path'
4
4
  import { fileURLToPath, pathToFileURL } from 'node:url'
5
5
  import { errorMessage, isRecord, kernelIncompatibility } from '@lincyaw/kernel'
6
+ import { packageExport } from '@lincyaw/kernel/node'
6
7
  import type { PresmiumNodePlugin, Severity } from '@lincyaw/kernel'
7
8
  import { createJiti } from 'jiti'
8
9
  import { satisfies, validRange } from 'semver'
9
- import { exports as resolveExports } from 'resolve.exports'
10
10
 
11
11
  export const NODE_PLUGIN_EXPORT = './presmium'
12
12
 
@@ -32,14 +32,34 @@ export interface PluginSources {
32
32
  }
33
33
 
34
34
  const jiti = createJiti(import.meta.url)
35
+ const failedEntries = new Set<string>()
35
36
 
36
37
  export async function loadPlugin(name: string, deckDir: string, sources?: PluginSources): Promise<{ loaded?: LoadedPlugin, problem?: PluginProblem }> {
37
38
  const problem = (severity: Severity, message: string): PluginProblem => ({ name, severity, message })
38
- const dir = findPackageDir(name, resolve(deckDir)) ?? bundledDir(name, sources)
39
+ const own = findPackageDir(name, resolve(deckDir))
40
+ const bundled = bundledDir(name, sources)
41
+ // An official plugin is versioned with the Presmium that runs it (its host, viewer and kernel): use the
42
+ // installation's copy whenever the project has a separate copy, even when both happen to have the same version.
43
+ // Otherwise the plugin's browser bundle can carry a second host module and fail with "no host installed".
44
+ if (own && bundled && name.startsWith(PRESMIUM_SCOPE) && realpathSync(own) !== realpathSync(bundled)) {
45
+ const result = await loadFrom(name, bundled, problem)
46
+ if (result.problem || packageVersion(own) === packageVersion(bundled)) return result
47
+ return { ...result, problem: problem('warning', `plugin "${name}": the project's ${packageVersion(own)} is not used; this Presmium runs its own ${packageVersion(bundled)}. Update the project's @lincyaw packages (pnpm up "@lincyaw/*") or run the project's own presmium (pnpm exec presmium)`) }
48
+ }
49
+ const dir = own ?? bundled
39
50
  if (!dir) return { problem: problem('error', `cannot load plugin "${name}": package not found from ${deckDir}`) }
40
51
  return loadFrom(name, dir, problem)
41
52
  }
42
53
 
54
+ function packageVersion(dir: string): string | undefined {
55
+ try {
56
+ const { version } = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: unknown }
57
+ return typeof version === 'string' ? version : undefined
58
+ } catch {
59
+ return undefined
60
+ }
61
+ }
62
+
43
63
  function bundledDir(name: string, sources?: PluginSources): string | undefined {
44
64
  if (!sources?.bundled) return undefined
45
65
  return BUNDLED.has(name) || dependsOn(sources.bundled, name) ? findPackageDir(name, sources.bundled) : undefined
@@ -114,19 +134,34 @@ async function loadFrom(name: string, dir: string, problem: (severity: Severity,
114
134
  const label = typeof pkg.name === 'string' ? ` (${pkg.name}${typeof pkg.version === 'string' ? ` ${pkg.version}` : ''})` : ''
115
135
  return { problem: problem('error', `plugin "${name}"${label} is not loaded: ${peers}`) }
116
136
  }
117
- const target = exportTarget(pkg, dir)
137
+ const target = packageExport(pkg, dir, NODE_PLUGIN_EXPORT)
118
138
  if (!target) return { loaded: { name, dir } }
119
139
  const file = fileURLToPath(new URL(target, pathToFileURL(`${dir}/`)))
120
140
  if (!existsSync(file)) {
121
141
  return { loaded: { name, dir }, problem: problem('warning', `plugin "${name}": ${NODE_PLUGIN_EXPORT} points to missing file ${target}; only its components are used`) }
122
142
  }
123
- const plugin = await jiti.import(file, { default: true })
143
+ const retry = failedEntries.has(file)
144
+ failedEntries.add(file)
145
+ let plugin: unknown
146
+ if (retry) {
147
+ // Re-evaluate failed entries; native ESM imports can retain an invalid export after repair.
148
+ delete jiti.cache[file]
149
+ const [kernel, contracts, node] = await Promise.all([
150
+ import('@lincyaw/kernel'), import('@lincyaw/kernel/contracts'), import('@lincyaw/kernel/node'),
151
+ ])
152
+ const loader = createJiti(import.meta.url, { virtualModules: {
153
+ '@lincyaw/kernel': kernel, '@lincyaw/kernel/contracts': contracts, '@lincyaw/kernel/node': node,
154
+ } })
155
+ const module = await loader.evalModule(readFileSync(file, 'utf8'), { filename: file, async: true, forceTranspile: true })
156
+ plugin = isRecord(module) && module.default !== undefined ? module.default : module
157
+ } else plugin = await jiti.import(file, { default: true })
124
158
  if (!isNodePlugin(plugin)) throw new Error(`default export of ${NODE_PLUGIN_EXPORT} is not a PresmiumNodePlugin`)
125
159
  const incompatible = plugin.kernel === undefined ? undefined : kernelIncompatibility(plugin.kernel)
126
160
  if (incompatible) {
127
161
  const version = plugin.version ? ` ${plugin.version}` : ''
128
162
  return { problem: problem('error', `plugin "${name}" (${plugin.id}${version}) is not loaded: ${incompatible}`) }
129
163
  }
164
+ failedEntries.delete(file)
130
165
  return { loaded: { name, dir, plugin, entry: file } }
131
166
  } catch (error) {
132
167
  return { problem: problem('error', `cannot load plugin "${name}": ${errorMessage(error)}`) }
@@ -185,35 +220,9 @@ export function findPackageDir(name: string, from: string, up = true): string |
185
220
  }
186
221
  }
187
222
 
188
- function exportTarget(pkg: PluginPackage, dir: string): string | undefined {
189
- let targets: string[] | void
190
- try {
191
- targets = resolveExports(pkg, NODE_PLUGIN_EXPORT)
192
- } catch {
193
- // A package with no matching Node export still contributes its components.
194
- return undefined
195
- }
196
- if (!targets?.length) return undefined
197
- const base = pathToFileURL(`${dir}/`)
198
- for (const target of targets) {
199
- const path = target.split(/[?#]/, 1)[0]!
200
- if (!path.startsWith('./') || /%2f|%5c/i.test(path)) continue
201
- try {
202
- const segments = path.slice(2).split(/[\\/]/).map(decodeURIComponent)
203
- if (segments.some(segment => /^(?:\.{1,2}|node_modules)$/i.test(segment))) continue
204
- const normalized = new URL(target, base)
205
- if (!normalized.href.startsWith(base.href)) continue
206
- return target
207
- } catch {
208
- // Invalid URL encoding cannot name a package file; arrays may provide another target.
209
- }
210
- }
211
- throw new Error(`${NODE_PLUGIN_EXPORT} has no valid package-relative Node target`)
212
- }
213
-
214
223
  function isNodePlugin(value: unknown): value is PresmiumNodePlugin {
215
224
  if (!isRecord(value) || typeof value.id !== 'string') return false
216
- const lists = ['resolvers', 'checks', 'directives', 'passes', 'executors', 'roles', 'tools'] as const
225
+ const lists = ['resolvers', 'checks', 'passes', 'executors', 'tools'] as const
217
226
  const renderer = value.renderer
218
227
  return lists.every(key => value[key] === undefined || Array.isArray(value[key]))
219
228
  && ['version', 'kernel'].every(key => value[key] === undefined || typeof value[key] === 'string')
package/src/renderers.ts CHANGED
@@ -4,7 +4,7 @@ import { errorMessage, findComponentRenderer, isRecord } from '@lincyaw/kernel'
4
4
  import type { BoundRendererExtension, ComponentNode, ComponentRenderer, Exporter, Finding, IRBlock, IRDocument, NodeVitePlugin, RenderContext, RenderOutput, Renderer } from '@lincyaw/kernel'
5
5
  import { documentLink, publishedAsset } from './assets.ts'
6
6
  import type { Compilation, Compiler } from './compiler.ts'
7
- import { portable } from './paths.ts'
7
+ import { portable, WORK_DIR } from './paths.ts'
8
8
  import { loadPlugin, pluginId } from './plugins.ts'
9
9
  import type { LoadedPlugin } from './plugins.ts'
10
10
  import { compileTranslations } from './translations.ts'
@@ -172,6 +172,24 @@ export function nodeVitePlugins(compilation: Pick<Compilation, 'plugins' | 'doc'
172
172
  })
173
173
  }
174
174
 
175
+ /** The checks of the document's renderers (`Renderer.check`), each given the whole document; a crashed check becomes a finding. */
176
+ export async function rendererChecks(compilation: Compilation): Promise<Finding[]> {
177
+ const { selected } = await selectRenderers(compilation)
178
+ const run = planRenderRun(compilation, selected, false)
179
+ const findings: Finding[] = []
180
+ for (const { renderer } of selected) {
181
+ if (!renderer.check) continue
182
+ const workDir = join(compilation.deckDir, WORK_DIR, renderer.id)
183
+ const ctx = renderContext(compilation, renderer.id, workDir, workDir, run, findings)
184
+ try {
185
+ for (const finding of await renderer.check(compilation.doc, ctx)) ctx.report(finding)
186
+ } catch (error) {
187
+ findings.push(renderFinding(compilation, 'error', `renderer ${renderer.id} could not check the document: ${errorMessage(error)}`))
188
+ }
189
+ }
190
+ return findings
191
+ }
192
+
175
193
  export function unsupportedBlocks(doc: IRDocument, renderer: Renderer, extensions: BoundRendererExtension[]): RenderOutput['skipped'] {
176
194
  const skipped: RenderOutput['skipped'] = []
177
195
  const visit = (section: string, blocks: IRBlock[]) => {
package/src/serve.ts CHANGED
@@ -42,7 +42,7 @@ export async function serveDirectory(root: string, options: ServeDirectoryOption
42
42
  response.writeHead(error.status ?? 500)
43
43
  response.end()
44
44
  }
45
- const shared = options.origins?.length ? cors({ origin: options.origins }) : undefined
45
+ const shared = options.origins ? cors({ origin: (origin, done) => done(null, origin !== undefined && options.origins!.includes(origin)) }) : undefined
46
46
  const attached = (request: { url?: string }, file: string) => (response: ServerResponse) => {
47
47
  if (new URL(request.url ?? '/', 'http://localhost').searchParams.has('download')) response.setHeader('Content-Disposition', contentDisposition(basename(file)))
48
48
  }
package/src/word.ts ADDED
@@ -0,0 +1,42 @@
1
+ import mammoth from 'mammoth'
2
+ import { fromHtml } from 'hast-util-from-html'
3
+ import type { MdastNode } from '@lincyaw/kernel'
4
+ import { defaultHandlers, toMdast } from 'hast-util-to-mdast'
5
+ import { toMarkdown } from 'mdast-util-to-markdown'
6
+ import { gfmToMarkdown } from 'mdast-util-gfm'
7
+
8
+ /** DOCX contributes semantic content; page layout, fonts and external files do not enter the document. */
9
+ export async function wordMarkdown(buffer: Buffer): Promise<{ text: string, assets: Map<string, Uint8Array>, warnings: number, tree: MdastNode }> {
10
+ const assets = new Map<string, Uint8Array>()
11
+ let imageNumber = 0
12
+ const extensions: Record<string, string> = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp', 'image/svg+xml': 'svg', 'image/tiff': 'tiff' }
13
+ const converted = await mammoth.convertToHtml({ buffer }, {
14
+ includeEmbeddedStyleMap: false,
15
+ styleMap: ["p[style-name='Title'] => h1:fresh"],
16
+ externalFileAccess: false,
17
+ convertImage: mammoth.images.imgElement(async image => {
18
+ const name = `word-image-${++imageNumber}.${extensions[image.contentType] ?? 'bin'}`
19
+ const bytes = await image.readAsBuffer()
20
+ assets.set(name, bytes)
21
+ return { src: name }
22
+ }),
23
+ })
24
+ const tree = toMdast(fromHtml(converted.value, { fragment: true }), {
25
+ handlers: {
26
+ table(state, node) {
27
+ const result = defaultHandlers.table!(state, node)
28
+ if (result && !Array.isArray(result) && result.type === 'table') {
29
+ const hasHeader = (element: typeof node): boolean => element.tagName === 'thead' || element.tagName === 'th'
30
+ || element.children.some(child => child.type === 'element' && hasHeader(child))
31
+ // The HTML converter inserts an empty Markdown header for Word tables without one.
32
+ // Keep the original rows in the editable tree; the text copy only supplies its title.
33
+ if (!hasHeader(node)) result.children.shift()
34
+ Object.assign(result, { headerRows: hasHeader(node) ? 1 : 0 })
35
+ }
36
+ return result
37
+ },
38
+ },
39
+ })
40
+ const text = toMarkdown(tree, { extensions: [gfmToMarkdown()], bullet: '-', fences: true })
41
+ return { text, tree: tree as unknown as MdastNode, assets, warnings: converted.messages.length }
42
+ }
package/src/directives.ts DELETED
@@ -1,117 +0,0 @@
1
- import type { DirectiveOptionType, Locale } from '@lincyaw/kernel'
2
-
3
- export interface DirectiveOptionInfo {
4
- type?: DirectiveOptionType
5
- doc?: Record<Locale, string>
6
- values?: string[]
7
- }
8
-
9
- export interface DirectiveInfo {
10
- name: string
11
- doc: Record<Locale, string>
12
- options: Record<string, DirectiveOptionInfo>
13
- }
14
-
15
- export const COMMON_DIRECTIVE_OPTIONS: Record<string, DirectiveOptionInfo> = {
16
- reveal: {
17
- doc: { 'zh-CN': '在下一步出现;`{slide}`、`{only}` 上写 `items` 时列表逐项出现。', 'en': 'Appears at the next step; `items` on `{slide}` and `{only}` reveals list items one per step.' },
18
- values: ['items'],
19
- },
20
- label: { type: 'string', doc: { 'zh-CN': '块 ID。', 'en': 'Block id.' } },
21
- audience: {
22
- type: 'string',
23
- doc: { 'zh-CN': '只给这些受众(逗号分隔),如 `teacher`;`presmium build --audience student` 不输出它。', 'en': 'Only for these audiences (comma-separated), e.g. `teacher`; `presmium build --audience student` leaves it out.' },
24
- values: ['teacher', 'student'],
25
- },
26
- }
27
-
28
- export const RUN_OPTION: DirectiveOptionInfo = {
29
- type: 'string',
30
- doc: { 'zh-CN': '`compile` 在构建时执行并录制输出,`live` 只在浏览器中执行,`both` 两者都做。', 'en': '`compile` records the output at build time, `live` runs in the browser, `both` does both.' },
31
- values: ['compile', 'live', 'both'],
32
- }
33
-
34
- const STEP_RANGE: Record<string, DirectiveOptionInfo> = {
35
- at: { type: 'number', doc: { 'zh-CN': '从指定步骤开始显示(从 0 开始),不能与 reveal 合用。', en: 'Shows from this zero-based step; cannot be combined with reveal.' } },
36
- until: { type: 'number', doc: { 'zh-CN': '到指定步骤时隐藏;回退时恢复。', en: 'Hides at this step and returns when stepping back.' } },
37
- }
38
-
39
- const TITLE = { 'zh-CN': '标题。', 'en': 'Title.' }
40
-
41
- const CODE_OPTIONS: Record<string, DirectiveOptionInfo> = {
42
- 'caption': { type: 'string', doc: TITLE },
43
- 'filename': { type: 'string', doc: TITLE },
44
- 'emphasize-lines': { type: 'string', doc: { 'zh-CN': '每一步都强调的行,如 `2, 4-5`。', 'en': 'Lines highlighted at every step, e.g. `2, 4-5`.' } },
45
- 'run': RUN_OPTION,
46
- 'executor': { type: 'string', doc: { 'zh-CN': '执行器 ID。', 'en': 'Executor id.' } },
47
- 'timeout': { type: 'number', doc: { 'zh-CN': '毫秒。', 'en': 'Milliseconds.' } },
48
- 'env': { type: 'string', doc: { 'zh-CN': '运行环境:头部 `execute.environments` 中的名字,或 `browser`。', 'en': 'Where it runs: a name of `execute.environments` in the headmatter, or `browser`.' } },
49
- 'session': { type: 'string', doc: { 'zh-CN': '执行会话:同一会话的代码块共享解释器。', 'en': 'Execution session: code blocks of one session share the interpreter.' } },
50
- 'echo': { type: 'string', doc: { 'zh-CN': '`false`:只显示输出,Markdown 输出按正文显示。', 'en': '`false`: only the output shows, Markdown output as prose.' }, values: ['false'] },
51
- }
52
-
53
- const CLASS: DirectiveOptionInfo = { type: 'string', doc: { 'zh-CN': 'CSS 类名。', 'en': 'CSS class names.' } }
54
-
55
- const LAYOUT_DIRECTIVES: DirectiveInfo[] = [
56
- {
57
- name: 'grid',
58
- doc: { 'zh-CN': '栅格:参数为四档屏宽(手机、小、中、大)的列数,如 `1 1 2 3`;正文为 `{card}` 或 `{grid-item}`。', 'en': 'A grid: the argument is the columns at four screen widths (phone, small, medium, large), e.g. `1 1 2 3`; the body holds `{card}` or `{grid-item}`.' },
59
- options: { class: CLASS },
60
- },
61
- {
62
- name: 'grid-item',
63
- doc: { 'zh-CN': '栅格中的一格。', 'en': 'An item of a grid.' },
64
- options: { columns: { type: 'number', doc: { 'zh-CN': '占一行 12 份中的几份。', 'en': 'How many twelfths of a row it takes.' } }, class: CLASS },
65
- },
66
- {
67
- name: 'card',
68
- doc: { 'zh-CN': '卡片:参数为标题;正文中 `^^^` 之前为页眉,`+++` 之后为页脚。', 'en': 'A card: the argument is its title; in the body, what precedes `^^^` is its header, what follows `+++` its footer.' },
69
- options: {
70
- link: { type: 'string', doc: { 'zh-CN': '整张卡片链接到的地址。', 'en': 'Where the whole card links to.' } },
71
- header: { type: 'string', doc: { 'zh-CN': '页眉。', 'en': 'Header.' } },
72
- footer: { type: 'string', doc: { 'zh-CN': '页脚。', 'en': 'Footer.' } },
73
- },
74
- },
75
- {
76
- name: 'tab-set',
77
- doc: { 'zh-CN': '一组选项卡;正文为 `{tab-item}`。', 'en': 'A set of tabs; the body holds `{tab-item}`.' },
78
- options: { class: CLASS },
79
- },
80
- {
81
- name: 'tab-item',
82
- doc: { 'zh-CN': '一个选项卡:参数为标题。', 'en': 'A tab: the argument is its title.' },
83
- options: {
84
- sync: { type: 'string', doc: { 'zh-CN': '同步键:选中它时,页面上同一键的选项卡一起切换。', 'en': 'Sync key: choosing it switches the tabs with the same key on the page.' } },
85
- selected: { type: 'boolean', doc: { 'zh-CN': '开始时选中。', 'en': 'Selected at first.' } },
86
- },
87
- },
88
- ]
89
-
90
- export const BUILTIN_DIRECTIVE_INFO: readonly DirectiveInfo[] = [
91
- { name: 'narration', doc: { 'zh-CN': '指定步骤的讲解与字幕;正文为 MyST。', en: 'Narration and captions for one step; the body is MyST.' }, options: { at: STEP_RANGE.at!, mode: { type: 'string', values: ['during', 'after'], doc: { 'zh-CN': 'during:边放边讲;after:动画播完再讲。', en: 'during: speak with the animation; after: speak after it finishes.' } } } },
92
- { name: 'slide', doc: { 'zh-CN': '上屏内容;正文为 MyST。', 'en': 'Content shown on screen; the body is MyST.' }, options: STEP_RANGE },
93
- { name: 'only', doc: { 'zh-CN': '只在这些渲染端出现的内容,如 `{only} web, notebook`。', 'en': 'Content limited to renderers, e.g. `{only} web, notebook`.' }, options: STEP_RANGE },
94
- { name: 'hints', doc: { 'zh-CN': '各渲染端的排版提示;正文为 YAML。', 'en': 'Layout hints per renderer; the body is YAML.' }, options: {} },
95
- { name: 'config', doc: { 'zh-CN': '只在本章节生效的插件配置;正文为 YAML,键为插件 ID。', 'en': 'Plugin configuration of this section; the body is YAML keyed by plugin id.' }, options: {} },
96
- { name: 'audience', doc: { 'zh-CN': '整个章节只给这些受众,如 `{audience} teacher`;放在章节顶层,没有正文。', 'en': 'The whole section is only for these audiences, e.g. `{audience} teacher`; at the top of a section, without a body.' }, options: {} },
97
- {
98
- name: 'component',
99
- doc: { 'zh-CN': '插件组件,如 `{component} PmQuiz`;正文为 YAML 属性。', 'en': 'A plugin component, e.g. `{component} PmQuiz`; the body is YAML props.' },
100
- options: { span: { type: 'number', doc: { 'zh-CN': '内部步数。', 'en': 'Internal steps.' } }, plugin: { type: 'string', doc: { 'zh-CN': '插件 ID。', 'en': 'Plugin id.' } } },
101
- },
102
- { name: 'include', doc: { 'zh-CN': '引入另一个源文件。', 'en': 'Includes another source file.' }, options: {} },
103
- {
104
- name: 'literalinclude',
105
- doc: { 'zh-CN': '以代码显示一个文件(或其中几行);参数为文件路径。', 'en': 'Shows a file (or some of its lines) as code; the argument is the file path.' },
106
- options: {
107
- 'language': { type: 'string', doc: { 'zh-CN': '语言;默认按扩展名。', 'en': 'Language; by default from the extension.' } },
108
- 'lines': { type: 'string', doc: { 'zh-CN': '只显示这些行,如 `2, 4-6`。', 'en': 'Only these lines, e.g. `2, 4-6`.' } },
109
- 'start-after': { type: 'string', doc: { 'zh-CN': '从含这段文字的行之后开始。', 'en': 'Starts after the line with this text.' } },
110
- 'end-before': { type: 'string', doc: { 'zh-CN': '到含这段文字的行之前结束。', 'en': 'Ends before the line with this text.' } },
111
- 'caption': CODE_OPTIONS.caption!,
112
- 'emphasize-lines': CODE_OPTIONS['emphasize-lines']!,
113
- },
114
- },
115
- ...['code', 'code-block', 'code-cell', 'sourcecode'].map(name => ({ name, doc: { 'zh-CN': '代码;参数为语言。', 'en': 'Code; the argument is the language.' }, options: CODE_OPTIONS })),
116
- ...LAYOUT_DIRECTIVES,
117
- ]