Diagnostics

Democraft emits stable DCxxxx diagnostics during static validation and live capture. Human-readable output includes repair suggestions; --json exposes the same fields for tools and coding agents.

How diagnostics surface

• CLI: democraft validate <demo> prints them to stderr. Add --json for machine-readable output.
• Studio: the staleness badge and capture progress surface validation failures inline.
• Capture: assertion failures (assert.visible, assert.text, assert.url) and unresolvable targets produce diagnostics that fail the capture.

Code ranges

Reading a diagnostic

A diagnostic has:

• code — the DC0xx identifier.
• message — human-readable description.
• path — semantic location in demo.ts.
• suggestion — a concrete repair action.
• docsUrl — stable documentation for the code.
• demoId / sceneId / stepId — where in the demo the issue is (when applicable).
• targetId — the target name involved (for locator/assertion issues).

Common codes

• DC001: invalid structure or configuration.
• DC002: duplicate scene or step ID.
• DC003: the author run callback threw.
• DC101: unknown target reference.
• DC102: invalid duration.
• DC103: invalid scene or missing callback.
• DC104: invalid step.
• DC105: unknown visual renderer.
• DC106: invalid target or locator list.
• DC107: unknown custom visual reference.
• DC108: custom visual props are not JSON-serializable.
• DC201: browser execution, assertion, target resolution, or screenshot failure.
• DC300–DC306: duplicate audio IDs, missing sources, invalid volume, invalid spans or fades, unsupported extensions, and malformed durations. See the audio guide.
• DC401: discovery origin blocked by the allowlist (pass --allow-origin).
• DC402: discovery URL used an unsafe scheme (use http/https).
• DC403: discovery timed out waiting for the page to settle.
• DC404: discovery was aborted (Ctrl+C).
• DC405: environment problem — run democraft doctor --json.
• DC406: a discovery locator matched multiple elements (scope to a region or pick a different candidate).
• DC407: no interactive elements discovered (page may need login).
• DC408: elements are inside a closed overlay (<dialog>, [hidden], or collapsed <details>). They're surfaced marked insideClosedOverlay: true; author the open-overlay step before capturing them.

Authentication preflight failures use semantic AUTH_* error codes rather than DCxxxx, because they describe a reusable session prerequisite rather than the demo definition. See authentication profiles for expiry, renewal, JSON output, and agent actions.

For AI agents

When generating a demo.ts, run democraft validate <demo> and fix every diagnostic before attempting a capture. The static pass catches structural issues (unknown target names, malformed steps, bad durations) without needing the target app — so it is cheap to iterate against.