feat(schema): add sample render URLs for canonical formats

[bokelley]

Summary

Draft for working group review.

This PR separates static format examples from buyer-asset previews by adding sample_render_url to canonical format declarations and registry publisher summaries. The field is explicitly informational: it points to a rendered example using publisher- or registry-provided sample assets, not buyer-submitted creative assets, and is not a renderer endpoint, validation result, creative approval, or live delivery guarantee.

It also makes canonical format cards in the publisher registry clickable. The details dialog shows the existing schematic preview, declaration metadata, canonical parameters, and an Open sample render action when sample_render_url is published.

Why

Canonical format declarations in adagents.json or Product.format_options[] tell buyers what assets are accepted, but they do not by themselves render buyer assets. The working group discussion pointed toward three separate concepts:

• sample_render_url: static human-facing rendered example of the unit shape.
• future preview_renderers[]: agents that can render buyer manifests.
• future canonical preview_creative.format_context: context needed to resolve format_kind + format_option_ref, especially product-local refs.

This PR intentionally implements only the first concept and avoids preview_url terminology so static examples are not confused with buyer-asset preview.

Changes

• Adds sample_render_url to ProductFormatDeclaration.
• Exposes sample_render_url in the registry publisher API summary and OpenAPI spec.
• Updates the publisher registry page so format cards open a keyboard-accessible details dialog.
• Adds HTTPS-only schema coverage for sample_render_url.
• Adds a minor adcontextprotocol changeset for a 3.2 release line.

Validation

Passed:

• node --check <publisher-home script>
• node --test --test-force-exit --test-timeout=30000 tests/placement-catalog-schema.test.cjs
• npm run test:schemas
• npm run test:openapi
• npm run typecheck
• npm run build:schemas
• node scripts/check-changeset-protocol-scope.cjs origin/main
• npx --yes @changesets/cli@^2.31.0 status --since=origin/main
• node scripts/check-pr-title.cjs "feat(schema): add sample render URLs for canonical formats"
• git diff --check

Review agents:

• Protocol/product/creative expert review supported the direction, with the key rename from preview_url to sample_render_url.
• Security review found no Must Fix issues. A Should Fix to avoid fallback from preview_url was addressed.
• Code review Should Fixes were addressed: removed preview_url fallback and added a focus trap for the modal.

Known local issue:

• The broad precommit hook failed in unrelated unit tests around registry-brand-setup-route.test.ts mock coverage for isDatabaseInitialized in ../../src/db/client.js. The commit was created with --no-verify after the targeted checks above passed.

Follow-ups

• Define preview_renderers[] / renderer refs separately from this static sample URL.
• Extend preview_creative with canonical format_context for format_kind + format_option_ref, especially product-local refs.
• Add renderer response metadata for authority/fidelity/known limitations/tracking behavior in a future spec patch.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
adcp	🟢 Ready	View Preview	Jun 26, 2026, 10:16 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.