Documentation
The Annotation Contract
Annotated HTML uses data-* attributes to describe the React component structure you want. The agent reads these annotations and produces TypeScript components that match your intent — no configuration files required.
What is Annotated HTML?
Annotated HTML is ordinary HTML with extra data-* attributes that describe component boundaries, prop bindings, state variables, and event handlers. You write it in the builder's code panel; the pipeline converts it to production React.
Each component block also carries two comment annotations at the top:
- Manifest
<!-- @component ComponentName --> - Props
<!-- @props { name: string; price: string } -->
The manifest tells the agent the component name; the props comment lets you declare TypeScript types explicitly rather than leaving the agent to infer them.
data-* Reference
| Attribute | Purpose | Example |
|---|---|---|
data-component="Name" | Marks the root element of a component. Name becomes the React component name. | <article data-component="PropertyCard"> |
data-prop="propName" | Maps element text content to a React prop. | <h3 data-prop="title">Default Text</h3> |
data-prop:attr="propName" | Maps an HTML attribute to a React prop. | <img data-prop:src="imageUrl" data-prop:alt="imageAlt"> |
data-state="varName=default" | Declares a useState variable on a client component. | <div data-client data-state="count=0"> |
data-client | Marks the component as a Client Component ("use client"). Required for state and handlers. | <form data-component="ContactForm" data-client> |
data-handler="handlerName" | Maps an event to a handler prop (onClick, onChange, etc.). | <button data-handler="onSubmit">Submit</button> |
data-repeat | Marks a list container. The direct child becomes the item template. | <ul data-repeat data-item="listing"> |
data-item="varName" | Names the iteration variable inside a data-repeat block. | <ul data-repeat data-item="listing"> |
data-as="element" | Overrides the rendered HTML element type. | <div data-as="section" data-component="Hero"> |
data-render="slotName" | Declares a named children slot. | <div data-render="actions"> |
The Pipeline
- 1
Validate
An annotation gate checks for at least one data-component and one binding annotation. Fails fast before any repo is touched.
- 2
Clone
The agent service clones the target project repo fresh into an isolated workspace and installs dependencies from a warm npm cache.
- 3
Agent Convert
The Claude Agent SDK query() loop reads your existing primitives, writes one .tsx per data-component, runs tsc --noEmit itself, and commits locally — up to maxRepairs iterations. It never pushes.
- 4
Independent Verify
The service re-runs tsc --noEmit in a clean subprocess the agent can't fake. A push happens only if the agent committed AND this check is clean.
- 5
Open PR for review
The verified commit is pushed to an isolated claude/ahb-* branch and a pull request is opened against the default branch (nextStep: await_review). You review the diff and the Vercel preview before anything reaches production.