SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsaxhub-annotation-standalone

axhub-annotation-standalone

Frontend & websites

View repository

Updated 10-16 14:59

About this skill

Axhub Annotation Standalone

When using @axhub/annotation in a standalone web project, use this skill. It only covers runtime integration: the page already has annotation data, and you only need to display markers, the annotation panel, the table of contents, and status controls.

Reference cases

Host Usage File
React AnnotationViewer component references/react-example.tsx
Plain HTML / DOM browser bundle + window.AxhubAnnotation.createAnnotationViewer references/axhub-annotation.global.js + references/html-example.html
Data source AnnotationSourceDocument JSON references/annotation-source.json

Integration prerequisites

  • Annotation data uses a single AnnotationSourceDocument, either statically imported or returned by the host loader.
  • Annotated elements should preferably have stable attributes, for example data-annotation-id。
  • Modern hosts such as React 18 / Vite can install @axhub/annotation and use ESM.
  • For plain HTML, DOM-only, React 17, Vue, Angular, managed injection, or file:// static pages, prefer the standalone browser bundle; the host is not required to install React / ReactDOM / antd.

Entry point selection

  • When the user explicitly says React 18, Vite, ESM, or an existing frontend project, use AnnotationViewer or ESM createAnnotationViewer。
  • When the user says plain HTML, static HTML, DOM, no build,file://, or just wants to open the HTML to see the result, you must use the browser bundle, which can be copied from this skill's references/axhub-annotation.global.js or from the npm package / local build output's dist/browser/axhub-annotation.global.js .
  • HTML mode only integrates the runtime provided by the package:window.AxhubAnnotation.createAnnotationViewer(...)。
  • Do not hand-write equivalent UI for markers, floating panels, table of contents, Markdown rendering, or status controls in the host; if the browser bundle is missing, build or copy the bundle first instead of redoing the UI.

React integration

  • Mount AnnotationViewer。
  • For multiple pages, pass options.currentPageId。
  • Table of contents route in options.onDirectoryRoute to let the host switch pages.
  • For status annotations use useProtoDevState() to read the controls value.
  • After publishing as HTML with source code, the published output will inject sourceReference, pointing to source/manifest.json; the host integration code does not need to generate it.

Plain HTML integration

  • Copy the browser bundle from the npm package, local build output, or this skill's references/axhub-annotation.global.js to the static assets directory; the npm / local build path is dist/browser/axhub-annotation.global.js。
  • Load <script src="./axhub-annotation.global.js"></script>in the page first; adjust the actual path according to the static assets directory.
  • Use window.AxhubAnnotation.createAnnotationViewer() to create the runtime.
  • Use getCurrentPageId to return the current page.
  • After switching pages, call viewer.refresh()。
  • Status controls can subscribe to window.__AXHUB_PROTO_DEV__, read values from getState() , and update the DOM.
  • If the page must be opened directly with file:// , avoid relying on cross-file fetch/import; the runtime must still come from the browser bundle.

Data key points

  • directory.nodes Put folder / route / markdown / link, no need for locator。
  • type: "markdown" Table of contents documents can directly write markdown body text.
  • When the table of contents document needs to be split into .md files, you can write markdownPath, for example docs/prd-03-status.md; this is a build-side convention, and the runtime still reads the inlined markdown。
  • markdownPath is only used for table of contents documents, not for marker annotation nodes.
  • data.nodes[] Put page markers, and there must be a locator。
  • When markers belong only to certain pages or states, write pageId。
  • For long body text use hasMarkdown: true + markdownMap[node.id]。
  • For status annotations write node controls; in JSON, only put serializable fields.
  • When the page has a dialog or overlay, inspect the actual DOM and write the active layer root selector containing the content into presentation.layerSelectors。
  • sourceReference is not placed in the JSON data source; only describe the source manifest location in the published package, and do not inline source files.

Acceptance

  1. Start the host preview.
  2. Confirm that the marker appears on the target element.
  3. Click the marker and verify that the short annotation or Markdown body is visible.
  4. Open the directory and verify route、markdown、link。
  5. Modify the state control and confirm that React state or plain DOM changes synchronously.
  6. Check whether the console has import, peer dependency, or locator errors.

Common mistakes

  • Do not write functions into JSON controls.
  • Do not hand-write annotation UI just to make a static page visible; HTML mode must also use @axhub/annotation 's browser runtime.
  • Do not jump to Vite/ESM integration first in plain HTML mode; the shortest path is browser bundle + window.AxhubAnnotation.createAnnotationViewer(...)。
  • Do not rely on fragile generated CSS selectors; if you can add data-annotation-id , add it.
  • Do not expect route to redirect automatically; the host must handle it in onDirectoryRoute .