API 参考

这份文档只覆盖当前 SDK 包根入口真正对外暴露的 API。

如果某个能力没有出现在这里，就不应该被当成公共 SDK 接口依赖。

这页更适合查入口和查名字，不负责展开讲原理或最佳实践。

`@mdanai/sdk/core`

这一组主要是协议和 Markdown 处理工具。

`parsePage(source)`

解析 .md 页面源，返回页面对象。

`composePage(source, { blocks })`

解析页面并附加运行时 block 内容，返回组合后的页面对象。

返回值还提供：

page.fragment(blockName)

这是当前推荐的 block 片段提取方式。

`validatePage(page)`

校验页面结构，包括：

block 名称
anchor 对齐
input 引用
操作约束

`parseMarkdownBody(body)`

解析 POST 请求体的 Markdown 形式。

`serializeMarkdownBody(values)`

把字段序列化成标准 Markdown 请求体。

`serializePage(page)`

把完整页面对象序列化成完整页面 Markdown。

`serializeFragment(fragment)`

把 block 级片段序列化成 Markdown 片段。

`MdanMarkdownRenderer`

统一的 Markdown 渲染扩展接口。同一个渲染器可以同时注入给：

createMdanServer({ markdownRenderer })
createHostedApp({ markdownRenderer })
mountMdanElements({ markdownRenderer })

`negotiateRepresentation(acceptHeader)`

根据 Accept 协商：

event-stream
markdown
html
not-acceptable

显式包含 text/markdown 时优先返回 markdown。

`@mdanai/sdk/server`

这一组主要是共享服务端运行时。

`createHostedApp({ pages, actions, ...options })`

创建一个更紧凑的 Hosted App 入口。

每个 action 都要显式声明：

target
methods
routePath
blockName
handler

每个 action 会自动拿到：

routePath
blockName
page()
block()

`createMdanServer(options?)`

创建服务端运行时。

常见可选项：

session
renderHtml
markdownRenderer

创建后可注册：

server.page(path, handler)
server.get(path, handler)
server.post(path, handler)
server.handle(request)

`block(page, blockName, result?)`

把 composed page 的某个 block 直接包装成成功 action result。

`stream(asyncIterable, result?)`

把异步片段流包装成 text/event-stream 响应。

`ok(result)`

构造成功 action result，适合完全手写片段的场景。

`fail(result)`

构造失败 action result，适合需要显式返回 4xx/5xx 且仍返回 md + mdan 片段的场景。

`signIn(session)`

创建登录 session mutation。

`signOut()`

创建登出 session mutation。

`refreshSession(session)`

创建续期 session mutation。

`@mdanai/sdk/server/node`

这一组主要是 Node host 适配器。

`createHost(server, options?)`

推荐的 Node http 入口。

支持：

rootRedirect
ignoreFavicon
transformHtml
staticFiles
staticMounts

`createNodeHost(server, options?)`

createHost(...) 的显式 Node 命名别名。

`createNodeRequestListener(server, options?)`

更底层的 Node RequestListener 适配器，适合你想自己包 http.createServer(...) 外壳时使用。

`@mdanai/sdk/server/bun`

这一组主要是 Bun host 适配器。

`createHost(server, options?)`

推荐的 Bun fetch 入口，适合直接接到 Bun.serve(...)。

支持：

rootRedirect
ignoreFavicon
transformHtml
staticFiles
staticMounts
maxBodyBytes

`@mdanai/sdk/web`

这一组主要是浏览器侧运行时。

`createHeadlessHost({ root, fetchImpl })`

浏览器侧运行时的推荐入口。

返回对象提供：

host.getSnapshot()
host.subscribe(listener)
host.submit(operation, values)
host.visit(target)
host.mount()
host.unmount()

`@mdanai/sdk/elements`

这一组主要是默认 UI 和自定义元素注册器。

`mountMdanElements({ root, host, markdownRenderer? })`

默认 UI 的推荐入口。它会：

注册官方 Web Components
基于当前状态渲染默认的页面、block 和表单 UI

`registerMdanElements()`

会注册这些默认 Web Components：

mdan-page
mdan-block
mdan-form
mdan-field
mdan-action
mdan-error

不再推荐依赖的旧路径

这些能力可能仍存在于包内部文件里，但不应该再作为公共 SDK 边界依赖：

fragmentForBlock() 包根调用
createNodeRequestListener() 包根调用
renderHtmlDocument() 包根调用
@mdanai/sdk/elements/register 子路径