The published version is an alpha, the root package is zero

The published version is an alpha, the root package is zero

Two releases exist, both alphas: v0.1.0-alpha.1 on 2026-05-29 and v0.1.0-alpha.2 on 2026-05-31. The repository itself was pushed on 2026-07-22, roughly seven weeks after the newer of the two, so the published artefacts describe an earlier state of the tree than the one you would clone.

The root package.json is not the published package at all. It is named agent-html-monorepo, marked private, and versioned 0.0.0, with workspaces pointing at apps/* and packages/*. So the version a user installs from npm lives in a package below the root, while the number you see in the repository is a placeholder that is never bumped. There is no tag that says otherwise: the release history is two entries and both are pre-release.

The declared engine floor is Node 22 or newer, and the package is an ES module, which sets the shape of anything you would script against it.

npm test is not a test command

The check script in the root package.json does three things, and the first is not a test. `test` runs canvas validation, then the canvas tests, then the desktop tests. Validation itself is three steps: a generated-catalogue freshness check, the CLI's own validate command, and dependency-cruiser run over the agent-html directory with errors as the output type.

"test": "npm run canvas:validate && npm run canvas:test && npm run desktop:test"

The build script opens the same way, running validation, then type checking, then the docs build, then the desktop build. So a generated file going stale, or a dependency drawn across a boundary that dependency-cruiser watches, stops both the tests and the build before a single assertion runs. The catalogue and the React canvas index both have sync and check modes as separate scripts, which is the mechanism that makes freshness testable at all.

Running `npx agent-html dev` and running `npm run dev` in the monorepo reach the same file, packages/cli/bin/agent-html.mjs, so the local workflow and the packaged CLI are one binary path.

Licence terms vary by package, in a repository labelled Apache-2.0

The licence section is four sentences and the shortest in the project. It says licence terms vary by package, points at the root LICENSE and at package-level licence files for details, and gives the summary as check the folder you use. The root package.json, meanwhile, records Apache-2.0.

Those two statements can both be true, since a monorepo root field and per-package licences are different things, but nothing in the README tells you which packages are exceptions. A workspace that ships a runtime package and a CLI package and a docs app has three plausible licence surfaces, and the instruction to check the folder is doing the work a table would otherwise do.

This is the kind of thing that surfaces late, in a legal review rather than in an install, so it is worth resolving before the first dependency lands in a product.

Block metadata is the trust boundary

The headless protocol from `@agent-html/react` defines an `Artifact` and a `Block`, and the point of a block is addressability. The host can target one visible region, place prompt actions on it, and pass compact context back into the agent workflow. The README states the constraint plainly: this happens without exposing host privileges to artifact source, and artifact source stays separate from application internals, host internals, generated bundles and privileged APIs.

That claim is enforced in more than prose. The validate step runs dependency-cruiser over the artifact workspace with errors as output, so a boundary violation fails the build rather than being reviewed, and the boundary is separate from the theme system too, since the host applies theme presets while artifact source stays on semantic tokens and Canvas classes. Presentation is deliberately the host's job.

The interesting consequence is that agent-written code runs inside a rendering host. The isolation is a dependency rule plus block scoping, and neither of those is a security sandbox.

Three commands to a canvas, then a prompt that reads two files

The quick start is deliberately short. Install the package, initialise a local workspace, start the host.

npm install agent-html
npx agent-html init
npx agent-html dev

After that the instruction is aimed at an agent rather than at you: build an artifact in agent-html/artifacts using Agent-HTML Canvas, and read agent-html/README.md and agent-html/AGENTS.md first. The prompt template is shipped as a text block, which tells you the intended workflow is that the agent self-orients from files on disk rather than from a chat transcript.

One naming wrinkle: the workspace directory the prompt tells you to write into is called agent-html, the same name as the npm package. In a monorepo where packages/* holds the CLI, three things share the word, so a path like agent-html/artifacts is worth checking against your own layout before you assume which one you are editing.

A desktop app and an archive that the README never mentions

The workspaces cover apps/* and packages/*, and the scripts name two app surfaces the README body never describes. Type checking fans out across the canvas project, a docs workspace and a desktop workspace, and the test and build scripts both end with desktop work, desktop tests and a desktop build.

The docs side is documented, sort of: the documentation list points at apps/docs/content/docs/index.mdx for the Canvas constitution, architecture, workspace, host, design-system and reference material. The desktop side is not mentioned at all, even though it has its own typecheck, lint, format, test and build scripts wired into the root commands. If you are evaluating whether this is a browser tool or something you can run natively, the scripts are the better source than the prose.

Then there is the `_archive` directory, described in one line as historical App and Runtime material kept for reference only. An archive inside the tree means grep and search results will keep surfacing code that is not part of the current system.

Two judgment systems in the tree, plus a lockfile for skills

The documentation list ends with two directories whose purpose is judgment rather than instruction. `taste/README.md` holds repo-level judgment systems, and `taste/agent-ergonomics/README.md` covers agent ergonomics, context routes and route checks for agent-facing workspace ergonomics. Neither is mentioned in the README body.

Around them sit AGENTS.md and CLAUDE.md at the root plus .agents/ and .claude/ directories, which is two sets of agent operating notes for two different tools, and INFINITE_CANVAS_DESIGN.md as a design document at the top level. There is also a skills-lock.json next to the root package-lock.json, so the skills the repository expects are pinned the way dependencies are.

The tooling matches the rest of the project: shadcn components via components.json, prettier and eslint configured separately with their own ignore files, a dependency-cruiser rule set, and a .gitnexusignore. A repository this concerned with where an artifact may reach from is also the repository telling you which agent to use to write one.

Editorial conclusion

Use it when the deliverable is something a person scans, compares or filters rather than reads, and expect to run the CLI yourself. Three things to settle first: the licence is per package rather than the single Apache-2.0 the root package.json declares, both published releases are alphas and the root package sits at 0.0.0, so there is no stable surface to pin, and a desktop app plus an archive of older material ship in the tree without being described in the README.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Sayhi-bzb/Agent-HTML on GitHub