用途
本技能面向独立 Web 项目的运行时接入需求，说明如何将 @axhub/annotation 添加到没有完整前端工程体系或需要独立运行的 Web 宿主中。它只处理运行时接入部分：页面已经持有标注数据，只需要展示 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 数据源里，只描述发布包中的源码清单位置，不内联源码文件。
验收
启动宿主预览。确认目标元素上出现 marker。点击 marker，能看到短标注或 Markdown 正文。打开目录，验证 route、markdown、link。修改状态控件，确认 React 状态或普通 DOM 同步变化。检查控制台是否有 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 里处理。