AI runtime integration contract

Category: Developer. Status: Normative.

This guide tells an AI coding system how to build applications using only the documented Vertcie runtime and public API.

Required reading order

1. Read platform-overview.md.
2. Choose the browser runtime SDK, public HTTP API, or both.
3. Read authentication.md and the selected interface guide.
4. For a custom Figma/React/Redux/Three.js configurator, read

runtime-custom-ui.md in full before generating state, selection, swatch, shader, material, or viewer code.

1. Do not assert fields or behavior absent from the public documentation.

For standalone image embeds, read runtime-images.md. Use its own image lifecycle and optional board-storage contract; do not couple it to Render Studio or generate a render-queue integration instead. Respect its implementation-preview deployment status.

Generation rules

• State the runtime version, API base URL, publishedFileId, latest/pinned revision policy, and authentication transport.
• Use placeholder hosts, product identifiers, signatures, origins, and keys.
• Prefer x-vertcie-key to the compatibility query parameter.
• Treat undocumented response members as opaque and preserve unknown fields when transforming payloads.
• Store stable published, option, shader, revision, and job identifiers—not signed URLs.
• Keep published content immutable. Selection updates create revisions.
• Use { publishedFileId, useLatest: true } for integrations that follow activated releases, or { publishedFileId, revision } for reproducible pinned integrations. Never combine useLatest: true with revision.
• Do not invent a new Published File ID for each update. A Published File ID is permanent; routine releases create immutable numbered revisions beneath it.
• Never infer storage paths, database fields, private endpoints, or administrative capabilities.
• Bound inputs, arrays, concurrency, timeouts, and retries.
• Retry only transient failures with exponential backoff and jitter.
• Do not retry validation, authentication, authorization, or missing-resource responses unchanged.

Interface selection

Required implementation output

An AI-generated implementation should include:

1. selected interface and documented exports/endpoints;
2. placeholder configuration and key handling;
3. origin policy;
4. loading, empty, invalid, unauthorized, missing, and unavailable states;
5. timeout, cancellation, and bounded retry behavior;
6. signed-URL refresh behavior;
7. cleanup for runtime instances and stale requests;
8. tests using generic non-production identifiers.

Forbidden assumptions

• A title is globally unique.
• A signature is unique without product context.
• Signed URLs are permanent.
• HTTP 200 proves asynchronous rendering is complete.
• Display labels are stable identifiers.
• Undocumented endpoints or fields are supported.
• A public runtime key grants capabilities beyond the documented runtime API.
• Missing labels, shaders, swatches, or materials may be inferred from GLTF

values, filenames, Figma layers, colors, or texture maps.

If a requested behavior is undocumented, identify the gap and request clarification rather than inventing an interface.