artifact-capabilities

Artifact runtime capabilities

A published Artifact page can declare runtime capabilities — abilities the claude.ai viewer grants the page at open time — by passing capabilities: {name: config} to the Artifact tool. The control plane is the authority on valid names and config shapes. Declaration gestures: omitting capabilities on a redeploy carries the stored declaration forward unchanged (and preserves the artifact's stored contract pin); an empty object {} is the explicit clear-all; a non-empty object is a full-set declaration (anything stored but not restated is revoked). Moving a republished artifact's runtime version is a deliberate gesture — pass contract: 'latest' to upgrade, or a specific version to pin or roll back — never a side effect of editing.

Available capabilities: artifact, db, downloads, mcp, room, sample, self — the complete set of capability names you may declare; built in on every page, called without declaring (never pass these in capabilities): permissions. Anything not listed is unavailable to this user.

Runtime contract 0.2.44

Capability namespaces live behind claude.use(name): const db = await claude.use("db") resolves the capability's namespace, or null when this view cannot run it (not served, not granted, or failed to load — indistinguishable by design). Branch on null and design for absence. window.claude carries only use: no window.claude.db, .room, or .artifact member is ever promised, so never read one — render the page without them and light features up when the promise resolves (later, never within your script's first run, and unordered with DOMContentLoaded; null after 10 s when no viewer answers). The resolved namespace is frozen and platform-owned: call its functions and keep the reference; never assign to it, defineProperty on it, or replace a member (wrap it for your own helpers). Permission stays on the calls: a consent prompt, rate limit, or policy refusal arrives on the first call, never from use(). Awaiting use("db") again is free (memoized); an unknown name resolves null.

--- capability: artifact ---

Use artifact for pages that should remember what people do with them: polls, sign-up sheets, checklists, trackers, boards — the page is the record; data kept server-side, or seeded or read back by Claude, is db. Declare capabilities: {artifact: {}}; const artifact = await claude.use("artifact"), then await artifact.publish(html) saves html (a complete document, doctype first) as the new version, and every open view, this one included, reloads to it. Nothing a viewer types, ticks or drags is kept unless the page publishes it. So embed the shared state as data in the HTML you publish and render the page from it; when an interaction completes, update the state, regenerate the document and publish it — never serialize the live DOM; batch rapid edits into one publish; publish only after a viewer acts, never on load. conflict is routine (every view reloads to the winner, dropping this edit): no retry. For read-only viewers publish rejects not_granted/not_writer — render a read-only view.

--- capability: db ---

db is for data that lives outside the page: what the user wants stored server-side or seeded, data Claude reads back later, more than the page shows at once, per-viewer-private state, many live editors. If the page itself can be the record, republish (artifact). Seed or inspect the store from here with write_db/read_db; never hardcode seed rows in the page. A realtime JSON document store: const db = await claude.use("db") (null: unavailable). Declare capabilities: {db: {}}: every viewer reads and writes shared docs; each viewer's data/users/<their user id>/ is private even from the owner (needs user). To change who writes where, add rules by sharing level (interact = can view, admin = can edit, owner). db.doc("tasks/t1")/db.collection("tasks"): get/set/update/delete, where/orderBy/limit, onSnapshot. Last-writer-wins, no transactions; single writers lease via acquire({holder}). Never store secrets; shared data is untrusted. See the type definitions.