@airalogy/aimd-renderer 2.5.0 → 2.7.0

package/README.md

@@ -1,12 +1,13 @@
 # @airalogy/aimd-renderer
 
 [![npm version](https://img.shields.io/npm/v/%40airalogy%2Faimd-renderer?logo=npm&color=cb3837)](https://www.npmjs.com/package/@airalogy/aimd-renderer)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/airalogy/aimd/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/airalogy/airalogy/blob/main/LICENSE)
 
 Rendering engine for AIMD (Airalogy Markdown): 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`.
 `parseAndExtract` returns the canonical core field structure, including simple `var` metadata in `fields.var_definitions`.
+Default `var` and `var_table` previews render AIMD `title`, preserve the canonical field id for automation, and expose `description` plus `example`/`examples` details only on hover or keyboard focus.
 
 > 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.
 
@@ -21,7 +22,7 @@ pnpm add @airalogy/aimd-renderer @airalogy/aimd-core
 ```ts
 import { renderToHtml, parseAndExtract } from "@airalogy/aimd-renderer"
 
-const content = "{{step|sample_preparation}}"
+const content = '{{var|sample_name: str, title="Sample name", description="Human-readable sample label", examples=["S-001"]}}'
 const { html } = await renderToHtml(content)
 const fields = parseAndExtract(content)
 
@@ -29,6 +30,20 @@ console.log(html)
 console.log(fields)
 ```
 
+## Review Marks
+
+Renderer output supports CriticMarkup-style review marks in normal Markdown text:
+
+| Purpose | AIMD source |
+| --- | --- |
+| Addition | `{++added text++}` |
+| Deletion | `{--deleted text--}` |
+| Substitution | `{~~old wording~>new wording~~}` |
+| Comment | `{>>review note<<}` |
+| Highlight | `{==important text==}` |
+
+These marks render through `renderToHtml`, `renderToVue`, and readonly `AiralogyMarkdown` fields. Inline code and fenced code blocks keep the source text literal.
+
 ## Assigner Visibility
 
 ```ts
@@ -95,14 +110,38 @@ const { nodes } = await renderToVue(content, {
 
 Use this when you want a ready-made Vue step-card surface without first mapping AIMD nodes into your own custom elements.
 
+## Readonly Record Rendering
+
+```ts
+import { renderReadonlyRecordToVue } from "@airalogy/aimd-renderer"
+
+const { nodes } = await renderReadonlyRecordToVue(protocolContent, {
+  data: {
+    var: {
+      sample_id: { value: "S-001" },
+      site_photo: "airalogy.id.file.site-photo.png",
+    },
+    check: { prepared: { checked: true } },
+  },
+}, {
+  resolveAsset: ({ fileId, fieldPath }) => assets.get(fileId ?? "") ?? assets.get(fieldPath) ?? null,
+})
+```
+
+Use this when a host app needs to show a completed AIMD protocol as a static document. The helper accepts either a Record payload wrapper with `data` or the `data` object itself, then renders the protocol in a readonly field context.
+
+`resolveAsset` lets the host map Record file ids, field paths, or archive manifest entries to `ReadonlyRecordAsset` objects. The renderer uses that mapping to show image/audio/video fields inline, render ordinary files as readonly links, and resolve Markdown image `src` values that point at Airalogy file ids. Archive readers should keep storage-specific work, such as building `blob:` URLs from `.aira` payloads, in the host app and pass only display-ready URLs into the renderer.
+
+Readonly `AiralogyMarkdown` values are rendered through the AIMD Vue renderer, so headings, lists, nested AIMD preview tokens, and resolved Markdown image assets appear as document content instead of raw Markdown source.
+
 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`
+- EN: <https://airalogy.github.io/airalogy/aimd/en/packages/aimd-renderer>
+- 中文: <https://airalogy.github.io/airalogy/aimd/zh/packages/aimd-renderer>
+- Source docs: `docs/aimd/en/packages/aimd-renderer.md`, `docs/aimd/zh/packages/aimd-renderer.md`
 
 ## Citation
 

package/README.zh-CN.md

@@ -1,12 +1,13 @@
 # @airalogy/aimd-renderer
 
 [![npm version](https://img.shields.io/npm/v/%40airalogy%2Faimd-renderer?logo=npm&color=cb3837)](https://www.npmjs.com/package/@airalogy/aimd-renderer)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/airalogy/aimd/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/airalogy/airalogy/blob/main/LICENSE)
 
 AIMD（Airalogy Markdown）渲染引擎：支持 HTML 渲染、Vue 渲染与字段提取。
 
 默认情况下，assigner 代码块不会出现在普通渲染输出中。只有在作者视图或调试视图中显式开启时，才会以折叠或展开形式显示；`parseAndExtract` 仍会保留相关字段元数据。
 `parseAndExtract` 返回 core 的规范字段结构，其中也包括 `fields.var_definitions` 里的普通 `var` 元数据。
+默认的 `var` 和 `var_table` 预览会渲染 AIMD 的 `title`，保留用于自动化的规范字段 id，并且只在 hover 或键盘 focus 时展示 `description` 与 `example`/`examples` 详情。
 
 > 协议级 AIMD 语法、assigner 语义与校验规则以 Airalogy 文档为准；`@airalogy/aimd-*` 文档只描述前端 parser、renderer、recorder 如何实现这些规范。
 
@@ -21,7 +22,7 @@ pnpm add @airalogy/aimd-renderer @airalogy/aimd-core
 ```ts
 import { renderToHtml, parseAndExtract } from "@airalogy/aimd-renderer"
 
-const content = "{{step|sample_preparation}}"
+const content = '{{var|sample_name: str, title="样本名", description="样本的人类可读标签", examples=["S-001"]}}'
 const { html } = await renderToHtml(content)
 const fields = parseAndExtract(content)
 
@@ -29,6 +30,20 @@ console.log(html)
 console.log(fields)
 ```
 
+## 审阅标记
+
+Renderer 输出支持普通 Markdown 文本中的 CriticMarkup 风格审阅标记：
+
+| 用途 | AIMD 源码 |
+| --- | --- |
+| 添加 | `{++新增文字++}` |
+| 删除 | `{--删除文字--}` |
+| 替换 | `{~~旧表述~>新表述~~}` |
+| 注释 | `{>>审阅备注<<}` |
+| 高亮 | `{==重点文字==}` |
+
+这些标记会通过 `renderToHtml`、`renderToVue` 和只读 `AiralogyMarkdown` 字段渲染出来。行内代码和 fenced 代码块会保留原始文本。
+
 ## Assigner 可见性
 
 ```ts
@@ -95,11 +110,35 @@ const { nodes } = await renderToVue(content, {
 
 当你想直接得到现成的 Vue 步骤卡片渲染，而不是先把 AIMD 节点映射到自定义元素时，可以使用这组 API。
 
+## 只读 Record 渲染
+
+```ts
+import { renderReadonlyRecordToVue } from "@airalogy/aimd-renderer"
+
+const { nodes } = await renderReadonlyRecordToVue(protocolContent, {
+  data: {
+    var: {
+      sample_id: { value: "S-001" },
+      site_photo: "airalogy.id.file.site-photo.png",
+    },
+    check: { prepared: { checked: true } },
+  },
+}, {
+  resolveAsset: ({ fileId, fieldPath }) => assets.get(fileId ?? "") ?? assets.get(fieldPath) ?? null,
+})
+```
+
+当宿主应用需要把已完成的 AIMD Protocol 展示为静态文档时，可以使用这个 helper。它既接受带 `data` 的 Record payload，也接受 `data` 对象本身，然后在只读字段上下文中渲染协议内容。
+
+`resolveAsset` 由宿主应用负责把 Record 文件 id、字段路径或 archive manifest 条目映射成 `ReadonlyRecordAsset`。renderer 会基于这个映射把图片、音频、视频字段内嵌渲染，把普通文件渲染为只读链接，并解析指向 Airalogy file id 的 Markdown 图片 `src`。`.aira` 读取、`blob:` URL 创建、对象存储签名 URL 等存储细节应留在宿主应用中，renderer 只接收可显示的 URL。
+
+只读 `AiralogyMarkdown` 值会通过 AIMD Vue renderer 渲染，因此标题、列表、嵌套 AIMD 预览 token，以及已解析的 Markdown 图片资源都会作为文档内容显示，而不是显示原始 Markdown 文本。
+
 在浏览器环境中调用异步渲染 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`
+- EN: <https://airalogy.github.io/airalogy/aimd/en/packages/aimd-renderer>
+- 中文: <https://airalogy.github.io/airalogy/aimd/zh/packages/aimd-renderer>
+- 文档源码：`docs/aimd/en/packages/aimd-renderer.md`、`docs/aimd/zh/packages/aimd-renderer.md`