@airalogy/aimd-renderer 2.4.1

package/README.md

@@ -0,0 +1,117 @@
+# @airalogy/aimd-renderer
+
+Rendering engine for AIMD: HTML output, Vue output, and field extraction.
+
+Assigner blocks are hidden from normal rendered output by default. You can opt into collapsed or expanded assigner display when building authoring/debug views, while extracted field metadata remains available through `parseAndExtract`.
+
+> Protocol-level AIMD syntax, assigner semantics, and validation rules are normative in Airalogy docs. `@airalogy/aimd-*` docs describe how the frontend parser, renderer, and recorder implement those rules.
+
+## Install
+
+```bash
+pnpm add @airalogy/aimd-renderer @airalogy/aimd-core
+```
+
+## Quick Start
+
+```ts
+import { renderToHtml, parseAndExtract } from "@airalogy/aimd-renderer"
+
+const content = "{{step|sample_preparation}}"
+const { html } = await renderToHtml(content)
+const fields = parseAndExtract(content)
+
+console.log(html)
+console.log(fields)
+```
+
+## Assigner Visibility
+
+```ts
+import { renderToHtml } from "@airalogy/aimd-renderer"
+
+const { html } = await renderToHtml(content, {
+  assignerVisibility: "collapsed", // "hidden" | "collapsed" | "expanded"
+})
+```
+
+`assignerVisibility` defaults to `"hidden"`.
+
+## Localization
+
+```ts
+import { renderToHtml } from "@airalogy/aimd-renderer"
+
+const content = "{{quiz|q1}}"
+
+const { html } = await renderToHtml(content, {
+  locale: "zh-CN",
+})
+```
+
+## Host Custom Elements
+
+```ts
+import {
+  createCustomElementAimdRenderer,
+  renderToHtml,
+} from "@airalogy/aimd-renderer"
+
+const { html } = await renderToHtml("{{step|verify, 2, title='Verify Output', check=True}}", {
+  groupStepBodies: true,
+  aimdElementRenderers: {
+    step: createCustomElementAimdRenderer("step-card", (node) => ({
+      "step-id": node.id,
+      "step-number": (node as any).step,
+      title: (node as any).title,
+      level: String((node as any).level),
+      "has-check": (node as any).check ? "true" : undefined,
+    }), {
+      container: true,
+      stripDefaultChildren: true,
+    }),
+  },
+})
+```
+
+This is intended for host apps that already have their own preview components and need AIMD HTML output to target those custom elements directly. Enable `groupStepBodies` when step containers should absorb following block content as their body/slot.
+
+## Reusable Step Card UI
+
+```ts
+import { createStepCardRenderer, renderToVue } from "@airalogy/aimd-renderer"
+
+const { nodes } = await renderToVue(content, {
+  groupStepBodies: true,
+  aimdRenderers: {
+    step: createStepCardRenderer(),
+  },
+})
+```
+
+Use this when you want a ready-made Vue step-card surface without first mapping AIMD nodes into your own custom elements.
+
+Math styles are loaded automatically when calling async render APIs (`renderToHtml` / `renderToVue`) in browser environments.  
+Use `@airalogy/aimd-renderer/styles` only if you want to preload styles manually.
+
+## Documentation
+
+- EN: <https://airalogy.github.io/aimd/en/packages/aimd-renderer>
+- 中文: <https://airalogy.github.io/aimd/zh/packages/aimd-renderer>
+- Source docs: `aimd/docs/en/packages/aimd-renderer.md`, `aimd/docs/zh/packages/aimd-renderer.md`
+
+## Citation
+
+If `@airalogy/aimd-renderer` is useful in your work, please cite the Airalogy paper:
+
+```bibtex
+@misc{yang2025airalogyaiempowereduniversaldata,
+      title={Airalogy: AI-empowered universal data digitization for research automation},
+      author={Zijie Yang and Qiji Zhou and Fang Guo and Sijie Zhang and Yexun Xi and Jinglei Nie and Yudian Zhu and Liping Huang and Chou Wu and Yonghe Xia and Xiaoyu Ma and Yingming Pu and Panzhong Lu and Junshu Pan and Mingtao Chen and Tiannan Guo and Yanmei Dou and Hongyu Chen and Anping Zeng and Jiaxing Huang and Tian Xu and Yue Zhang},
+      year={2025},
+      eprint={2506.18586},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2506.18586},
+}
+```

package/README.zh-CN.md

@@ -0,0 +1,101 @@
+# @airalogy/aimd-renderer
+
+AIMD 渲染引擎：支持 HTML 渲染、Vue 渲染与字段提取。
+
+默认情况下，assigner 代码块不会出现在普通渲染输出中。只有在作者视图或调试视图中显式开启时，才会以折叠或展开形式显示；`parseAndExtract` 仍会保留相关字段元数据。
+
+> 协议级 AIMD 语法、assigner 语义与校验规则以 Airalogy 文档为准；`@airalogy/aimd-*` 文档只描述前端 parser、renderer、recorder 如何实现这些规范。
+
+## 安装
+
+```bash
+pnpm add @airalogy/aimd-renderer @airalogy/aimd-core
+```
+
+## 快速开始
+
+```ts
+import { renderToHtml, parseAndExtract } from "@airalogy/aimd-renderer"
+
+const content = "{{step|sample_preparation}}"
+const { html } = await renderToHtml(content)
+const fields = parseAndExtract(content)
+
+console.log(html)
+console.log(fields)
+```
+
+## Assigner 可见性
+
+```ts
+import { renderToHtml } from "@airalogy/aimd-renderer"
+
+const { html } = await renderToHtml(content, {
+  assignerVisibility: "collapsed", // "hidden" | "collapsed" | "expanded"
+})
+```
+
+`assignerVisibility` 默认值是 `"hidden"`。
+
+## 本地化
+
+```ts
+import { renderToHtml } from "@airalogy/aimd-renderer"
+
+const content = "{{quiz|q1}}"
+
+const { html } = await renderToHtml(content, {
+  locale: "zh-CN",
+})
+```
+
+## 宿主自定义元素
+
+```ts
+import {
+  createCustomElementAimdRenderer,
+  renderToHtml,
+} from "@airalogy/aimd-renderer"
+
+const { html } = await renderToHtml("{{step|verify, 2, title='Verify Output', check=True}}", {
+  groupStepBodies: true,
+  aimdElementRenderers: {
+    step: createCustomElementAimdRenderer("step-card", (node) => ({
+      "step-id": node.id,
+      "step-number": (node as any).step,
+      title: (node as any).title,
+      level: String((node as any).level),
+      "has-check": (node as any).check ? "true" : undefined,
+    }), {
+      container: true,
+      stripDefaultChildren: true,
+    }),
+  },
+})
+```
+
+当宿主应用已经有自己的预览组件时，可以用这种方式把 AIMD HTML 输出直接映射到自定义元素。若希望步骤节点把后续块级正文一起吸收到 body / slot 中，请启用 `groupStepBodies`。
+
+## 可复用 Step Card UI
+
+```ts
+import { createStepCardRenderer, renderToVue } from "@airalogy/aimd-renderer"
+
+const { nodes } = await renderToVue(content, {
+  groupStepBodies: true,
+  aimdRenderers: {
+    step: createStepCardRenderer(),
+  },
+})
+```
+
+当你想直接得到现成的 Vue 步骤卡片渲染，而不是先把 AIMD 节点映射到自定义元素时，可以使用这组 API。
+
+在浏览器环境中调用异步渲染 API（`renderToHtml` / `renderToVue`）时，会自动加载公式样式。  
+只有在你希望手动预加载样式时，才需要引入 `@airalogy/aimd-renderer/styles`。
+
+## 文档
+
+- EN: <https://airalogy.github.io/aimd/en/packages/aimd-renderer>
+- 中文: <https://airalogy.github.io/aimd/zh/packages/aimd-renderer>
+- 文档源码：`aimd/docs/en/packages/aimd-renderer.md`、`aimd/docs/zh/packages/aimd-renderer.md`