Workspace

agent-html is the Canvas workspace: the agent's local operating context.

It owns the instructions, reusable resources, fixtures, and durable work products an agent may read and compose while writing React artifacts:

agent-html/AGENTS.md
  -> workspace rules and operating instructions

agent-html/README.md
  -> cold-start reading path and portable source workspace contract

agent-html/components.json
  -> shadcn workspace discovery config

agent-html/tsconfig.json
  -> local TypeScript and editor discovery config

agent-html/package.json
  -> source-only workspace dependency metadata

agent-html/styles/index.css
  -> CSS runtime entrypoint

agent-html/styles/base.css
  -> base stylesheet rules such as text selection

agent-html/styles/materials
  -> raw material values and Tailwind bridge

agent-html/styles/kits
  -> standard kits for artifact root, content scale, and rich component values

agent-html/styles/layouts/index.css
  -> artifact layout style API entrypoint

agent-html/styles/layouts/composition.css
  -> artifact-consumable L2 composition classes

agent-html/styles/internal
  -> Artifact root and artifact-adjacent implementation styles

agent-html/theme
  -> host-owned theme preset registry and shadcn CSS sources

agent-html/components/ui
  -> local visual primitives such as button, card, tabs, dialog, and select

agent-html/components/*.tsx
  -> reusable rich components

agent-html/hooks
  -> reusable React behavior

agent-html/lib
  -> pure helpers and transforms

agent-html/types
  -> shared source types

agent-html/assets
  -> bundle-time artifact assets imported by artifact source

agent-html/public
  -> shared static files served by URL at /__agent-html/public/<path>

agent-html/artifacts
  -> durable agent-authored work products

agent-html/artifacts/<artifact>/data
  -> artifact-local data files

agent-html/artifacts/<artifact>/public
  -> artifact-owned static files served by URL at /__agent-html/artifacts/<artifact>/public/<path>

README.md, AGENTS.md, components.json, tsconfig.json, and package.json stay at the workspace root because agents, shadcn, TypeScript, editors, and dependency tooling discover them from there. agent-html/package.json is source dependency metadata only. agent-html is a portable source workspace, not a vendored runtime package; it does not keep package-lock.json, manifest.json, node_modules, generated bundles, .vite, dist, build, or vendored dependency folders.

Canvas CLI and host packages provide the runtime React, bundling, stylesheet, icon, and preview environment. Local Canvas primitives may list source dependencies in agent-html/package.json; artifact authors should prefer existing ui, hooks, lib, and assets resources before introducing a third-party dependency. New dependencies need an explicit owner: source-only workspace metadata when local Canvas source imports them, or CLI/host package dependencies when the runtime host must provide them. When a local Canvas source dependency is used at runtime, both owners are needed: agent-html/package.json records the source metadata and the CLI package provides the installed runtime dependency. The dev host resolves package imports with Vite import entries and exact package aliases; it must not rely on agent-html/node_modules.

Use agent-html/assets for files that artifact source imports into the bundle, such as images or media used by React components. Use agent-html/artifacts/<artifact>/public for artifact-owned URL-addressed files that should stay static and be referenced through artifactPublicUrlFactory from agent-html/lib/public-url. The helper resolves to /__agent-html/artifacts/<artifact>/public/<path>. Use agent-html/public only for shared URL-addressed files such as host icons or cross-artifact resources, and reference them through sharedPublicUrl. Public files are not imported from artifact source.

Authoring Contract

Artifacts import protocol and optional interaction helpers from @agent-html/react. Local resources use relative paths:

import {
  Artifact,
  Block,
  useInstrumentedValueChange,
} from "@agent-html/react"

import { Button } from "../components/ui/button"
import { useFilter } from "../hooks/use-filter"
import { formatDate } from "../lib/format-date"
import rows from "./data/summary"
import diagramUrl from "../assets/diagram.svg"

Use Artifact as the top-level wrapper. It owns the readable root container and accepts only title and children. Root width and block gap are configured by --canvas-artifact-* tokens in agent-html/styles/kits/artifact.css; background and foreground follow the shared foundation tokens. Wrap each major semantic region in Block. Use stable, unique, readable, kebab-case block ids. Block is a protocol marker only: use id, title, and children, and put layout or visual treatment inside the block content. The host owns block prompt actions through its inspection overlay; artifact source does not render action markers.

Overview artifact entries may delegate block content to split implementation files in a matching directory, using <block-id>.block.tsx. The Canvas prompt pipeline addresses these files through artifactEntry + blockId and may include the resolved implementationPath in prompt metadata.

Use interaction helpers only for artifact-local control instrumentation. They emit agent-html:state-change events; they do not provide filesystem, shell, MCP, Codex app-server, or host API access.

Artifact content uses Canvas public composition classes backed by --canvas-content-* tokens for spacing, typography, panel padding, icon-box size, and grid gap. Panel radius, border, and icon-box color come from shared semantic tokens. Host chrome tokens and implementation styles live under packages/cli/src/host/styles.

Artifact code must not call the filesystem, shell commands, MCP servers, Codex app-server, or privileged host APIs.