Skip to content

feat(web): add dynamic OpenGraph truth cards and social PNG download #1865

Description

@JOY

Goal

Implement Package 8A Feature F3 (approved by JOY on 2026-11-22 from Docs/Proposals/2026-11-22-de-xuat-tinh-nang-moi-phase-8.html): generate brand-authentic dark-theme Dynamic OpenGraph truth cards (1200x630) for product detail pages, 1v1 versus matchups, and Deal Radar, plus a 1-click downloadable social Truth Card PNG (4:5 / 1200x630) in ProductShareAuditButton.tsx with zero database migrations.

Requirements

  1. Validated, Rate-Limited Truth Card Image Endpoint (/api/v1/rate/og + apps/web/src/lib/og-truth-card.tsx):
    • Render crisp dark-theme (#0f1113 background, #161a1e surface, #FF2E29 accent) PNG cards for 3 verified entity types:
      1. product: product title, verified floor price in VND across X / 22 stores, price spread, Bayesian star score, 6-axis review trust signal, and Deal Radar badge.
      2. versus: head-to-head 2-device comparison card (prices, overall star scores, category winner badge).
      3. deals: Deal Radar summary card highlighting verified multi-store floor deals across 22 retail chains.
    • Support format=og (1200x630) and format=social (1080x1350 4:5 portrait for Threads/TikTok/Facebook/Zalo) with full Vietnamese and Czech diacritics (using bundled @fontsource / sharp SVG-to-PNG or next/og ImageResponse with local font bytes - zero external network calls!).
    • Anti-abuse & security: NEVER render arbitrary user-supplied query text onto images! Only accept validated slug / versus / locale identifiers backed by real cached catalog records (404 when unknown), protect with BoundedSlidingWindowRateLimiter, and set Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400.
  2. OpenGraph & Twitter Card Metadata Wiring + 1-Click PNG Download:
    • Wire openGraph.images and twitter.images in generateMetadata of product detail pages, /compare/[versus]/page.tsx, and /deals/page.tsx (without touching CompareWorkspace.tsx or DealFinderWorkspace.tsx).
    • Add a 1-click "Download Truth Card (PNG)" action inside ProductShareAuditButton.tsx ("productDetail" locale namespace).

Approach

Implement the image generator + route handler /api/v1/rate/og/route.ts using cached BFF reads (withRateDataCache), wire openGraph.images / twitter.images in seo.ts / page generateMetadata, add the download action to ProductShareAuditButton.tsx, and add unit/route tests in apps/web/src/lib/__tests__/seo.test.ts and product-detail-copy.test.ts.

Acceptance

  • /api/v1/rate/og returns valid image/png (1200x630 and 1080x1350) with Cache-Control headers for real products, versus pairs, and deals in vi, en, and cs, and returns 400/404/429 safely on invalid, unknown, or rate-limited requests without rendering untrusted query strings.
  • Product detail, /compare/[versus], and /deals HTML metadata include og:image and twitter:image pointing to the canonical OG truth card URL.
  • ProductShareAuditButton.tsx lets users download the PNG truth card in 1 click across vi, en, and cs.
  • Full monorepo typecheck, lint, test, build, and Playwright E2E pass.

Files

  • apps/web/src/lib/og-truth-card.tsx (or .ts)
  • apps/web/src/app/api/v1/rate/og/route.ts
  • apps/web/src/lib/seo.ts & page generateMetadata in category [slug]/page.tsx, compare/[versus]/page.tsx, deals/page.tsx
  • apps/web/src/components/leaderboard/ProductShareAuditButton.tsx
  • apps/web/locales/{vi,en,cs}.json ("productDetail" namespace only)
  • apps/web/src/lib/__tests__/seo.test.ts
  • apps/web/src/lib/__tests__/product-detail-copy.test.ts

Activity

  1. added
    featureNew feature or enhancement
    status:readyTask ready to be picked up by an Agent
    po:antigravityDispatched by the Antigravity Product Owner
    on Nov 22, 2026
  2. JOY commented on Nov 22, 2026

    @JOY
    ContributorAuthor

    🔒 [Agent: Brand] Claim lock refs/claims/1865 taken by claimant antigravity:0a1440be-c5c8-4ac0-8916-8f45aad1d36c (Status: in-progress).

  3. added
    status:in-progressTask currently claimed and being worked on by an Agent
    agent:brandClaimed by Agent: Brand
    and removed
    status:readyTask ready to be picked up by an Agent
    on Nov 22, 2026
  4. self-assigned this
    on Nov 22, 2026
  5. JOY commented on Nov 22, 2026

    @JOY
    ContributorAuthor

    [Agent: Brand] Claimed this issue on branch feat/1865-og-truth-cards (Claimant: antigravity:0a1440be-c5c8-4ac0-8916-8f45aad1d36c). Starting implementation of Dynamic OpenGraph truth cards (/api/v1/rate/og, og-truth-card.tsx), metadata wiring, and 1-click social PNG download in ProductShareAuditButton.tsx.

  6. added
    status:in-reviewTask completed and waiting for review / PR merge
    and removed
    status:in-progressTask currently claimed and being worked on by an Agent
    on Nov 22, 2026
  7. JOY commented on Nov 22, 2026

    @JOY
    ContributorAuthor

    [Agent: Brand] Opened PR #1868 (feat/1865-og-truth-cards -> dev, commit 7755067f), completed two independent fresh-context subagent reviews (all Round-1 P1/P2/P3 findings resolved and tested), and verified local test, typecheck, lint, and build. Waiting for GitHub required checks on PR #1868.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

agent:brandClaimed by Agent: Brandarea:webfeatureNew feature or enhancementpo:antigravityDispatched by the Antigravity Product Ownerstatus:in-reviewTask completed and waiting for review / PR merge

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions