---
name: axhub-annotation-standalone
description: Use when adding @axhub/annotation to standalone React apps, plain HTML pages, Vite prototypes, or other web hosts that need annotation markers, directories, Markdown notes, or state controls.
---

# Axhub Annotation Standalone

在独立 Web 项目中使用 `@axhub/annotation` 时，用这个技能。它只说明运行时接入：页面已有标注数据，只需要展示 marker、标注面板、目录和状态控件。

## 参考案例

| 宿主 | 使用方式 | 文件 |
| --- | --- | --- |
| React | `AnnotationViewer` 组件 | `references/react-example.tsx` |
| 普通 HTML / DOM | browser bundle + `window.AxhubAnnotation.createAnnotationViewer` | `references/axhub-annotation.global.js` + `references/html-example.html` |
| 数据源 | `AnnotationSourceDocument` JSON | `references/annotation-source.json` |

## 接入前提

- 标注数据使用一份 `AnnotationSourceDocument`，静态 import 或由宿主 loader 返回。
- 被标注元素优先加稳定属性，例如 `data-annotation-id`。
- React 18 / Vite 等现代宿主可以安装 `@axhub/annotation` 并走 ESM。
- 普通 HTML、DOM-only、React 17、Vue、Angular、托管注入或 `file://` 静态页，优先走 standalone browser bundle，不要求宿主安装 React / ReactDOM / antd。

## 入口选择

- 用户明确说 React 18、Vite、ESM 或已有前端工程时，使用 `AnnotationViewer` 或 ESM `createAnnotationViewer`。
- 用户说普通 HTML、静态 HTML、DOM、无构建、`file://`、只想打开 HTML 看效果，必须使用 browser bundle，可从本 skill 的 `references/axhub-annotation.global.js` 或 npm 包 / 本地构建产物里的 `dist/browser/axhub-annotation.global.js` 复制。
- HTML 模式只接入包提供的 runtime：`window.AxhubAnnotation.createAnnotationViewer(...)`。
- 不要在宿主里手写 marker、浮层面板、目录、Markdown 渲染或状态控件的等价 UI；如果缺少 browser bundle，先构建或复制 bundle，而不是重做 UI。

## React 接入

- 挂载 `AnnotationViewer`。
- 多页面时传 `options.currentPageId`。
- 目录 `route` 在 `options.onDirectoryRoute` 中交给宿主切页。
- 状态标注用 `useProtoDevState()` 读取 `controls` 值。
- 发布为带源码 HTML 后，发布产物会注入 `sourceReference`，指向 `source/manifest.json`；宿主接入代码不需要生成它。

## 普通 HTML 接入

- 从 npm 包、本地构建产物或本 skill 的 `references/axhub-annotation.global.js` 复制 browser bundle 到静态资源目录；npm / 本地构建路径为 `dist/browser/axhub-annotation.global.js`。
- 在页面里先加载 `<script src="./axhub-annotation.global.js"></script>`，实际路径按静态资源目录调整。
- 用 `window.AxhubAnnotation.createAnnotationViewer()` 创建运行时。
- 用 `getCurrentPageId` 返回当前页面。
- 切页后调用 `viewer.refresh()`。
- 状态控件可订阅 `window.__AXHUB_PROTO_DEV__`，从 `getState()` 读值并更新 DOM。
- 如果页面必须直接用 `file://` 打开，避免依赖跨文件 fetch/import；运行时仍然必须来自 browser bundle。

## 数据要点

- `directory.nodes` 放 `folder` / `route` / `markdown` / `link`，不需要 `locator`。
- `type: "markdown"` 目录文档可以直接写 `markdown` 正文。
- 需要把目录文档拆成 `.md` 文件时，可以写 `markdownPath`，例如 `docs/prd-03-status.md`；这是构建侧约定，运行时仍读取内联后的 `markdown`。
- `markdownPath` 只用于目录文档，不用于 marker 标注节点。
- `data.nodes[]` 放页面 marker，必须有能在宿主页面解析到的 `locator`。
- marker 只属于某些页面或状态时，写 `pageId`。
- 长正文用 `hasMarkdown: true` + `markdownMap[node.id]`。
- 状态标注写节点 `controls`；JSON 里只放可序列化字段。
- 页面有对话框或遮罩层时，检查实际 DOM，把包含内容的活动层根选择器写入 `presentation.layerSelectors`。
- `sourceReference` 不放在 JSON 数据源里，只描述发布包中的源码清单位置，不内联源码文件。

## 验收

1. 启动宿主预览。
2. 确认目标元素上出现 marker。
3. 点击 marker，能看到短标注或 Markdown 正文。
4. 打开目录，验证 `route`、`markdown`、`link`。
5. 修改状态控件，确认 React 状态或普通 DOM 同步变化。
6. 检查控制台是否有 import、peer dependency 或 locator 错误。

## 常见错误

- 不要把函数写进 JSON controls。
- 不要为了让静态页可见而手写标注 UI；HTML 模式也必须使用 `@axhub/annotation` 的 browser runtime。
- 不要在普通 HTML 模式里先跳到 Vite/ESM 接入；最短路径是 browser bundle + `window.AxhubAnnotation.createAnnotationViewer(...)`。
- 不要依赖脆弱的生成 CSS 选择器；能加 `data-annotation-id` 就加。
- 不要期待 `route` 自动跳转；宿主必须在 `onDirectoryRoute` 里处理。