feat(preview-utils): adopt self-rendering product_card (5/5 of #1902 sweep — CI green!)

[bokelley]

Stacked on #1902. Final structural-break follow-up.

AdCP 3.1.0-beta.2 changed `product_card` from a creative-agent-rendered shape (`{ format_id, manifest }`) to a self-contained visual card (`{ image, title, description, price_label, cta_label }`). The card IS the preview — no creative-agent round-trip required. (Schema note: "Receivers render the card directly from these fields.")

Changes

• `batchPreviewProducts` rewritten — extracts `product_card.image?.url` directly from the inline card instead of calling `creativeAgent.previewCreative()`.
• `creativeAgentClient` and `options` parameters retained for signature compatibility (renamed to underscore-prefixed unused args). Marked `@deprecated`; planned removal in 8.0 final or 9.0.
• `format_card` and `batchPreviewFormats` unchanged — only `product_card` had this spec migration in 3.1.0-beta.2.

Adopter migration

• Existing calls to `batchPreviewProducts(products, creativeAgent)` keep returning `PreviewResult[]` with `previewUrl` populated from the new inline `image.url`. No code change required.
• Direct field access (`product.product_card?.image?.url`) is now the recommended path; `batchPreviewProducts` is `@deprecated`.

Verification

• `tsc --noEmit` on `tsconfig.lib.json`: foundation 17 → 13 errors on this PR alone. With all 5 stacked PRs (fix(types): handle OutcomeMeasurement rename (1/5 of #1902 sweep) #1903, feat(test-controller): promote query_upstream_traffic to first-class scenario (2/5 of #1902 sweep) #1905, fix(governance): drop categories from governance_agents wire (3/5 of #1902 sweep) #1906, feat(manifest-helpers): handle AssetVariant array slots (4/5 of #1902 sweep) #1907, this) merged into the foundation: CI should be green.
• No tests directly reference `batchPreviewProducts` — risk-free.
• prettier --check clean.

Stack status — CI ready

This closes the 5/5 structural breaks listed in #1902:

• ✅ fix(types): handle OutcomeMeasurement rename (1/5 of #1902 sweep) #1903 — OutcomeMeasurement rename
• ✅ feat(test-controller): promote query_upstream_traffic to first-class scenario (2/5 of #1902 sweep) #1905 — ControllerScenario exhaustiveness
• ✅ fix(governance): drop categories from governance_agents wire (3/5 of #1902 sweep) #1906 — governance_agents categories
• ✅ feat(manifest-helpers): handle AssetVariant array slots (4/5 of #1902 sweep) #1907 — AssetVariant array slots
• ✅ this — product_card self-rendering

Once all five are merged into `bokelley/cut-8-0-beta`, #1902 can be marked ready and the whole stack admin-merged.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

[aao-ipr-bot]

LGTM. Right shape for the 3.1.0-beta.2 migration — the spec note says "Receivers render the card directly from these fields," so a direct product_card?.image?.url read is the witness move; the creative-agent round-trip was translation the new spec doesn't ask for.

Things I checked

• Generated type matches the new card shape — src/lib/types/tools.generated.ts:1337-1359 is { image, title, description, price_label, cta_label } with ImageAsset.url: string required.
• New body is correct — optional chain handles product_card absent, image absent, and url absent (the last can't happen given the generated type, but the guard is cheap). No fabrication, no fallback URL.
• async over a sync body is the right deprecation shim — call sites keep awaiting, return type is byte-identical.
• Signature compatibility holds — _creativeAgentClient, _options underscore-prefixed; adopters' calls keep compiling.
• Changeset is major (.changeset/product-card-self-rendering.md). Correct: previewId no longer populated on the hot path and error strings disappear. Both are observable, both warrant the bump.
• Orphaned helpers (getCacheKey, getCachedPreview, setCachedPreview, previewCache, clearPreviewCache) — all still load-bearing for batchPreviewFormats at src/lib/utils/preview-utils.ts:173-308, and clearPreviewCache is re-exported. Leave them.
• No tests reference batchPreviewProducts directly (grep clean). Example callers at examples/batch-preview-test.ts:127,151,253 and examples/debug-preview-with-logging.ts:44 keep compiling against the preserved signature.

Follow-ups (non-blocking — file as issues)

• Examples still call batchPreviewProducts and demonstrate cache reuse (examples/batch-preview-test.ts:151). The cache claim is no longer meaningful for products. Either point the examples at product.product_card?.image?.url directly or add a banner noting the deprecation. Out of scope for this PR.
• Loss of error: 'Preview generation failed' for product rows is the right call under the new spec — "no image.url" is a data state, not a failure — but worth a sentence in release notes for adopters who were branching on result.error. The changeset prose covers the happy path; the silent-error case is what catches people.

Minor nits (non-blocking)

1. Unused import. src/lib/utils/preview-utils.ts:5 imports PreviewCreativeResponse which is unused (pre-existing, not introduced here — PreviewCreativeRequest on the same line is still used by batchPreviewFormats at L248). Trivial split-and-drop while you're here.
2. Redundant eslint pragma. src/lib/utils/preview-utils.ts:130 — // eslint-disable-next-line @typescript-eslint/no-unused-vars above export async function only suppresses the next line; the unused args are two and three lines down. The _-prefix on L133-134 is what's actually doing the work in most configs. Pragma can be dropped.

Safe to merge. Closes 5/5 of the #1902 sweep.