prototype-annotation

Prototype Annotations

Overview

This is the technical usage guide for Axhub Make client prototype annotations. It is intended for src/prototypes/ multi-prototype projects, explaining how to connect @axhub/annotation to any prototype, and how to maintain three types of annotation capabilities: directory, component annotations, and component states.

This skill only constrains the technical integration approach. Do not use it to decide annotation copy, design principles, delivery scenarios, or page styles on the user's behalf; these are governed by user requirements, prototype materials, and project specifications.

Usage Scenarios

Scenario	Capability Used	Data Location
Directory	Prototype entry, document entry, link entry	directory.nodes
Component Annotations	Attach markers and descriptions to page elements	data.nodes[] + locator
Component States	Provide switchable states for a component	data.nodes[].controls + useProtoDevState

Main Flow

1. Find the target prototype:src/prototypes/<prototype-id>/。
2. Read the prototype's page code, existing annotation-source.json and adjacent materials.
3. Determine which type of capability is needed this time: directory, component annotations, or component states.
4. Use the AnnotationSourceDocument wire format to maintain annotation-source.json。
5. In the page, statically import the same JSON via AnnotationViewer .
6. For multi-page or multi-state prototypes, pass the current page/state to currentPageId, or return it via getCurrentPageId .
7. Directory route nodes only call back to the host; in onDirectoryRoute , switch pages, states, data sources, or URLs.
8. Run verification according to the scope of changes, usually:

   npm run typecheck
   node scripts/check-app-ready.mjs /prototypes/<prototype-name>
   

When field structures, integration code, or control examples are needed, read references/axhub-annotation.md。

Directory

The directory is not a page marker and does not need locator. It is used to organize prototypes, documents, and links in a multi-prototype project into the annotation panel.

• folder: Group directory node.
• route: Handled by the host; can switch the current prototype page, state, data source, or route.
• markdown: Open an inline Markdown document.
• markdownPath: Only used for directory Markdown documents; can point to docs/*.mdwithin the current prototype directory; the client build pipeline inlines it as the runtime-read markdown。
• link: Open another prototype address, resource address, or external link.

For multi-prototype entries, prefer link pointing to /prototypes/<prototype-id> or a full URL; for entries to pages/states within the current prototype, use route。

The relative link here is only used for annotation runtime data. When replying to the user, requesting acceptance, or providing a preview entry, you must use the full targetUrlreturned by the ready check, or complete /prototypes/<prototype-id> into the full URL of the current dev server according to project rules.

Component Annotations

Component annotations use data.nodes[]. Each node needs at least a stable id、locator, body fields, and time fields.

• Prefer adding a stable selector to the target element, for example data-annotation-id="<node-id>"。
• pageId can be omitted; when omitted, the node is displayed in all current page contexts.
• pageId can be a string or an array of strings, used to limit which pages/states the marker appears on.
• hasMarkdown: false uses annotationText and images。
• hasMarkdown: true use markdownMap[node.id], at runtime it will ignore annotationText and images。
• When the page has a dialog or overlay, inspect the actual DOM and write the active layer root selector containing the popup content into presentation.layerSelectors。

Component state

Component state uses the node's controls. At runtime, control values are written to proto dev state, and the page reads and renders the corresponding state through useProtoDevState .

• In JSON, controls only writes serializable fields.
• Supported control types include input、inputNumber、select、segmented、switch、checkbox、slider、textarea、text、button、colorPicker。
• For three or fewer discrete options, usually use segmented, so the options are displayed directly.
• If the directory route also needs to switch state, in onDirectoryRoute read node.payload and call the page's own state switching logic or setProtoDevState。

Usage notes

• Do not write parameters that do not exist in the current public API;AnnotationViewerOptions is based on the @axhub/annotation type definition.
• Do not mistakenly write directory nodes as component annotation nodes; directories have no marker.
• Do not write component state only into the page's local state; state that needs to appear in the annotation panel must be written into the node controls。
• Do not rely on unstable CSS selectors as the sole locating method; when stable attributes can be added, add them first.
• showBrandLink、defaultMarkerIndexVisible、renderToolbarActions Display enhancement options such as these should only be set when the user explicitly requests a brand entry, default display of sequence numbers, or custom toolbar actions; keep the default configuration for regular annotation integration.
• Markdown images must be published with the prototype: put them in the current prototype assets/ and use the final accessible URL; do not use local paths,/api/markdown-file or ../assets/...。