lazy-loading done

openspec/changes/reduce-bounce-rate/specs/interaction-tracking-taxonomy/spec.md

@@ -0,0 +1,88 @@
+## ADDED Requirements
+
+### Requirement: Media preview event for in-page content views
+The tracking taxonomy MUST define a `media_preview` event for content card clicks that open an in-page media modal instead of navigating outbound.
+
+The `media_preview` event MUST include the following properties:
+- `target_id` (stable unique identifier for the card, following the existing `card.{placement}.{source}.{id}` format)
+- `placement` (the listing surface where the card appears, e.g., `home.newest`, `videos.list`, `podcast.list`)
+- `title` (human-readable content title, truncated to max 160 characters)
+- `type` (`video` or `podcast_episode`)
+- `source` (`youtube` or `podcast`)
+
+#### Scenario: Video card click emits media_preview
+- **WHEN** a user clicks a YouTube video card on the videos listing page
+- **THEN** the system emits a `media_preview` event with `target_id=card.videos.list.youtube.{id}`, `placement=videos.list`, `type=video`, and `source=youtube`
+
+#### Scenario: Podcast card click emits media_preview on homepage
+- **WHEN** a user clicks a podcast card in the homepage podcast section
+- **THEN** the system emits a `media_preview` event with `target_id=card.home.podcast.podcast.{id}`, `placement=home.podcast`, `type=podcast_episode`, and `source=podcast`
+
+### Requirement: Media preview close event
+The tracking taxonomy MUST define a `media_preview_close` event emitted when the media modal is dismissed.
+
+The `media_preview_close` event MUST include:
+- `target_id` (the same identifier as the `media_preview` event that opened the modal)
+- `close_method` (one of: `button`, `escape`, `backdrop`)
+
+#### Scenario: User closes modal via Escape key
+- **WHEN** the user presses Escape to close the media modal that was opened from a video card
+- **THEN** the system emits a `media_preview_close` event with the original `target_id` and `close_method=escape`
+
+#### Scenario: User closes modal via close button
+- **WHEN** the user clicks the close button on the media modal
+- **THEN** the system emits a `media_preview_close` event with the original `target_id` and `close_method=button`
+
+#### Scenario: User closes modal via backdrop click
+- **WHEN** the user clicks the backdrop outside the modal content
+- **THEN** the system emits a `media_preview_close` event with the original `target_id` and `close_method=backdrop`
+
+### Requirement: Modal CTA namespace
+The tracking taxonomy MUST define a `media_modal` placement value for CTA interactions within the media modal.
+
+Modal CTAs MUST use `target_id` values in the namespace `modal.cta.{action}.{platform}` where `action` is `follow` or `view` and `platform` is `youtube` or `spotify`.
+
+#### Scenario: User clicks "View on YouTube" in modal
+- **WHEN** the user clicks the "View on YouTube" CTA inside the media modal
+- **THEN** the system emits a `cta_click` event with `target_id=modal.cta.view.youtube`, `placement=media_modal`, and `platform=youtube`
+
+#### Scenario: User clicks "Follow on Spotify" in modal
+- **WHEN** the user clicks the "Follow on Spotify" CTA inside the media modal
+- **THEN** the system emits a `cta_click` event with `target_id=modal.cta.follow.spotify`, `placement=media_modal`, and `platform=spotify`
+
+## MODIFIED Requirements
+
+### Requirement: Minimum required properties
+Every tracked click event MUST include, at minimum:
+- `target_id`
+- `placement`
+
+For links, the event MUST also include:
+- `target_url` (or a stable target identifier that can be mapped to a URL)
+
+For content-related links (clickables representing a specific piece of content), the event MUST also include:
+- `title` (human-readable content title)
+- `type` (content type identifier)
+
+The `type` value MUST be one of:
+- `video`
+- `podcast_episode`
+- `blog_post`
+- `blog_page`
+
+For non-link clickables that trigger in-page actions (e.g., modal openers), the event MUST also include:
+- `title` (human-readable content title)
+- `type` (content type identifier)
+- `source` (content source identifier)
+
+#### Scenario: Tracking a content card click
+- **WHEN** a user clicks a content card link
+- **THEN** the emitted event includes `target_id`, `placement`, and `target_url`
+
+#### Scenario: Tracking a content link includes title and type
+- **WHEN** a user clicks a content-related link that represents a specific content item
+- **THEN** the emitted event includes `target_id`, `placement`, `target_url`, `title`, and `type`
+
+#### Scenario: Tracking a modal-trigger card includes title, type, and source
+- **WHEN** a user clicks a content card that opens a media modal instead of navigating
+- **THEN** the emitted event includes `target_id`, `placement`, `title`, `type`, and `source` (no `target_url` since the user stays on-page)