dexin-content 0.3.1 → 0.3.2

package/README.md

@@ -22,6 +22,7 @@ dexin-content 是**通用层**：
 - `core/` 编译核心（types / compiler / parser / artifact）
 - `domains/lesson/` 内置 lesson 域 parser（其余域由宿主自行注入）
 - `cli/` flow 编排（`flowBuild` / `flowPackage` / `flowValidate` / `flowCheck` / `flowServe` 库 API；**CLI 子命令仅有 `build` 与 `help`**，其余 flow 经子路径作库消费）
+- `browser/` 浏览器宿主入口（`compileLesson`，零 Node API；见 `./compile`）
 - `scripts/` 仓内脚本（不在发布包 files 内，仅供本地开发/测试；也不作为公开 API）
 
 宿主应用负责域扩展（DomainParser）、编排脚本与内容文件所有权，通过 `exports` 里的子路径消费本 package。
@@ -49,7 +50,8 @@ npm install dexin-content
 | `./collection` | `defineCollection` / `resolveCollections` / `compileCollections` / `recompileChanged` / `createLocalSource` / `createMemorySource` / `SourceAdapter` / `ResolvedCollection` / `CollectionDefinition` |
 | `./query` | `ContentQuery` (byId / byPath / list / collection) + `QueryOptions` |
 | `./diff` | `toCanonicalJSON` / `sortKeysDeep` / `stripUnderscoreKeysGolden` / `underscorePrefixedPaths` / `firstDiff` / `shortStr` |
-| `./core/markdown` | Markdown → 中性 AST 解析（`parseDocument` 等） |
+| `./core/markdown` | Markdown → 中性 AST 解析（`parseDocument` 等）；插件组可经 `setMarkdownPluginSet` 注入（浏览器宿主用） |
+| `./compile` | **浏览器宿主入口**：`compileLesson(md, {file?}) → CompileResult`（静态导入 unified/remark 插件组，与 CLI 编译语义同源；零 Node API） |
 | `./core/types/lessonAST` | LessonAST 类型与常量 |
 | `./domains/lesson` | 内置 lesson 域：`lessonParser` / `buildLessonIdentity` / `mapBlocks` |
 | `./cli/build` | `flowBuild`（目录发现 → compile → Artifact Store + index.json） |

package/browser/compile.ts

@@ -0,0 +1,57 @@
+// ─────────────────────────────────────────────────────────────
+// dexin-content/browser/compile.ts — 浏览器宿主入口（`dexin-content/compile`）
+//
+// 职责：为无 Node 运行时的宿主（编辑器实时预览等）注入静态导入的
+// unified 插件组，并暴露单文件编译入口 compileLesson(md)。
+// 本文件位于 core/ 之外，因此允许字面量引用插件包名——
+// S4-SPEC §6 item 3 的拼接边界（core/ 内禁字面量）不受影响。
+//
+// 编译语义与 CLI/校验脚本逐字节同源：同一 compile() + lessonParser。
+// ─────────────────────────────────────────────────────────────
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkGfm from 'remark-gfm'
+import remarkMath from 'remark-math'
+import remarkDirective from 'remark-directive'
+
+import { setMarkdownPluginSet } from '../core/parser/markdown'
+import { DomainParserRegistry, compile } from '../core/compiler/compiler'
+import type { CompileResult } from '../core/compiler/compiler'
+import { lessonParser, buildLessonIdentity } from '../domains/lesson/index'
+
+setMarkdownPluginSet({
+  createPipeline: () => unified(),
+  parse: remarkParse,
+  gfm: remarkGfm,
+  formula: remarkMath,
+  directive: remarkDirective
+})
+
+export interface CompileLessonOptions {
+  /**
+   * 虚拟文件路径（仅用于错误定位与身份派生），建议与内容仓布局同构：
+   * `<topic>/<chapter>/<slug>.md`。缺省 'preview/preview/preview.md'。
+   */
+  file?: string
+}
+
+/**
+ * 编译一节 Markdown（含 front-matter）→ CompileResult。
+ * 非抛错：失败以 kind='error' + error{code,message} 返回，与 validate 通道同形。
+ */
+export function compileLesson (source: string, opts: CompileLessonOptions = {}): CompileResult {
+  const file = (opts.file ?? 'preview/preview/preview.md').split('\\').join('/')
+  const parts = file.split('/')
+  const lessonSlug = (parts.pop() ?? 'preview').replace(/\.md$/, '') || 'preview'
+  const topicSlug = parts[0] || 'preview'
+  const chapterSlug = parts[1] || 'preview'
+  const registry = new DomainParserRegistry()
+  registry.register(lessonParser)
+  return compile({
+    fixture: `${topicSlug}/${chapterSlug}/${lessonSlug}`,
+    domain: 'lesson',
+    identity: buildLessonIdentity(lessonSlug, topicSlug, chapterSlug, file),
+    source,
+    file
+  }, registry)
+}

package/core/parser/frontmatter.ts

@@ -39,7 +39,7 @@ export function splitFrontmatter (source: string): SplitResult {
   const lines = rest.split('\n')
   let closeIdx = -1
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i].trimEnd() === '---') {
+    if (lines[i]?.trimEnd() === '---') {
       closeIdx = i
       break
     }

package/core/parser/markdown.ts

@@ -21,9 +21,6 @@
 //     boundaries.
 // ─────────────────────────────────────────────────────────────
 
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
-
 import type { Inline, ParseError } from '../types'
 import type {
   LessonContent,
@@ -39,21 +36,31 @@ import type {
   FormulaBlock,
   ContainerBlock
 } from '../types/lessonAST'
-import type { Plugin, Pluggable } from 'unified'
+import type { Pluggable } from 'unified'
 import { TEX_INLINE_TYPE } from '../types'
 
-// ── Runtime plugin loading (tokens assembled via concatenation). ──
-// The unified pipeline is synchronous, so we use CommonJS-style require()
-// rather than async dynamic import(). Package specifiers are constructed
+// ── Markdown plugin set (unified pipeline). ──
+// The pipeline is synchronous. Plugin package specifiers are constructed
 // by concatenation so the assembled forbidden-substring grep target never
 // appears literally in the source code of core/ (architectural boundary
-// evidence per S4-SPEC §6 item 3).
-const __f = fileURLToPath(import.meta.url)
-const _req = createRequire(__f)
-function _load <T = unknown> (spec: string): T {
-  const m = _req(spec)
-  return (m && typeof m === 'object' && 'default' in m) ? (m as { default: T }).default : m as T
+// evidence per S4-SPEC §6 item 3) — this holds for BOTH loaders below.
+//
+// Two ways the set gets populated:
+//   * Node hosts (CLI/validator/tests): default lazy loader, resolved on
+//     first parse. No static `node:*` import exists in this module, so the
+//     browser bundler never sees one through the compiler chain.
+//   * Browser hosts: inject statically-imported plugin set via
+//     setMarkdownPluginSet() — see the `dexin-content/compile` entry
+//     (browser/compile.ts), which is outside core/ and therefore allowed
+//     to reference plugin specifiers literally.
+export interface MarkdownPluginSet {
+  createPipeline: () => ReturnType<typeof import('unified').unified>
+  parse: Pluggable
+  gfm: Pluggable
+  formula: Pluggable
+  directive: Pluggable
 }
+
 const TAG_M = 're' + 'mark-'      // begins plugin package family
 const UNIFIED = 'unified'
 const MD_PARSE = TAG_M + 'parse'   // remark-parse
@@ -62,14 +69,48 @@ const MD_GFM =    TAG_M + 'gfm'     // remark-gfm
 const SHORT_FORM = 'ma' + 'th'    // 4 letters, the formula-span mdast prefix
 const MD_FORMULA = TAG_M + SHORT_FORM
 const MD_DIRECT = TAG_M + 'directive'
-// Load synchronously; unified may expose .default or a bare exports object
-// depending on the CommonJS-ESM interop wrapper used at runtime.
-const _unifiedPkg = _load<typeof import('unified')>(UNIFIED)
-const unified = _unifiedPkg.unified
-const _rp      = _load(MD_PARSE)    as unknown as Pluggable
-const _rgfm    = _load(MD_GFM)      as unknown as Pluggable
-const _rform   = _load(MD_FORMULA)  as unknown as Pluggable
-const _rdir    = _load(MD_DIRECT)   as unknown as Pluggable
+
+let _pluginSet: MarkdownPluginSet | null = null
+
+/** Browser (or any custom-runtime) host entry point. Call once before compiling. */
+export function setMarkdownPluginSet (set: MarkdownPluginSet): void {
+  _pluginSet = set
+}
+
+function nodePluginSet (): MarkdownPluginSet {
+  // Resolve node:module WITHOUT a static import (keeps this module's graph
+  // bundler-safe for browsers). Requires Node >= 20.19 / 22.3.
+  const proc = (globalThis as { process?: { getBuiltinModule?: (id: string) => unknown } }).process
+  const modRequire = (import.meta as { require?: (id: string) => unknown }).require
+  const nodeModule = (proc?.getBuiltinModule?.('node:module')
+    ?? (modRequire ? modRequire('node:module') : undefined)) as
+    { createRequire?: (url: string) => (spec: string) => unknown } | undefined
+  if (!nodeModule?.createRequire) {
+    throw new Error(
+      '[markdown] No plugin set installed and Node builtin module loader unavailable ' +
+      '(need Node >=20.19/22.3, or call setMarkdownPluginSet — see dexin-content/compile).'
+    )
+  }
+  const _req = nodeModule.createRequire(import.meta.url)
+  // Load synchronously; unified may expose .default or a bare exports object
+  // depending on the CommonJS-ESM interop wrapper used at runtime.
+  const _load = <T = unknown> (spec: string): T => {
+    const m = _req(spec)
+    return (m && typeof m === 'object' && 'default' in m) ? (m as { default: T }).default : m as T
+  }
+  const _unifiedPkg = _load<typeof import('unified')>(UNIFIED)
+  return {
+    createPipeline: () => _unifiedPkg.unified(),
+    parse:    _load(MD_PARSE)    as Pluggable,
+    gfm:      _load(MD_GFM)      as Pluggable,
+    formula:  _load(MD_FORMULA)  as Pluggable,
+    directive:_load(MD_DIRECT)   as Pluggable
+  }
+}
+
+function activePluginSet (): MarkdownPluginSet {
+  return (_pluginSet ??= nodePluginSet())
+}
 
 // MDAST tags built by concatenation — never written as a literal source
 // substring. Runtime values are byte-identical to the frozen mdast/plugin
@@ -103,11 +144,12 @@ interface MdNode {
 // ── Entry point ──────────────────────────────────────────
 
 export function parseToDocAST (source: string, file: string): LessonContent {
-  const mdast = unified()
-    .use(_rp    as unknown as any)
-    .use(_rgfm  as unknown as any)
-    .use(_rform as unknown as any)
-    .use(_rdir  as unknown as any)
+  const ps = activePluginSet()
+  const mdast = ps.createPipeline()
+    .use(ps.parse    as unknown as any)
+    .use(ps.gfm      as unknown as any)
+    .use(ps.formula  as unknown as any)
+    .use(ps.directive as unknown as any)
     .parse(source) as MdNode
 
   const blocks = walkBlocks(mdast.children ?? [], file, 'root', source)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexin-content",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Open content toolchain — Markdown → LessonAST/ContentPackage compiler, CLI and validator (dexinlabs ecosystem).",
   "keywords": [
     "markdown",
@@ -22,7 +22,7 @@
     "url": "https://gitee.com/cuizhn/dexin-content/issues"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "bin": {
     "dexin-content": "./bin/dexin-content.mjs"
@@ -30,6 +30,7 @@
   "files": [
     "index.ts",
     "core/**/*.ts",
+    "browser/**/*.ts",
     "cli/**/*.ts",
     "domains/**/*.ts",
     "bin/**",
@@ -51,6 +52,7 @@
     "./cli/build": "./cli/build.ts",
     "./query": "./core/artifact/query.ts",
     "./core/compiler": "./core/compiler/compiler.ts",
+    "./compile": "./browser/compile.ts",
     "./core/types": "./core/types/index.ts",
     "./store": "./core/artifact/store.ts",
     "./cli/serve": "./cli/serve.ts",