p08-seo-tweaks

openspec/changes/p08-seo-tweaks/specs/delivery-and-rendering-performance/spec.md

@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: HTTP delivery applies compression and cache policy
+The system SHALL apply transport-level compression and explicit cache directives for static assets, API responses, and public HTML routes.
+
+#### Scenario: Compressed responses are available for eligible payloads
+- **WHEN** a client requests compressible content that exceeds the compression threshold
+- **THEN** the response is served with gzip compression
+- **AND** response headers advertise the selected content encoding
+
+#### Scenario: Route classes receive deterministic cache-control directives
+- **WHEN** clients request static assets, API responses, or HTML page routes
+- **THEN** each route class returns a cache policy aligned to its freshness requirements
+- **AND** cache directives are explicit and testable from response headers
+
+### Requirement: Media rendering optimizes perceived loading performance
+The system SHALL lazy-load non-critical images and render shimmer placeholders until image load completion or fallback resolution.
+
+#### Scenario: Feed and modal images lazy-load with placeholders
+- **WHEN** feed or modal images have not completed loading
+- **THEN** a shimmer placeholder is visible for the pending image region
+- **AND** the placeholder is removed after load or fallback error handling completes
+
+#### Scenario: Image rendering reduces layout shift risk
+- **WHEN** article images are rendered in hero, feed, or modal contexts
+- **THEN** image elements include explicit dimensions and async decoding hints
+- **AND** layout remains stable while content loads
+
+### Requirement: Smooth scrolling behavior is consistently enabled
+The system SHALL provide smooth scrolling behavior for in-page navigation and user-initiated scroll interactions.
+
+#### Scenario: In-page navigation uses smooth scrolling
+- **WHEN** users navigate to in-page anchors or equivalent interactions
+- **THEN** scrolling transitions occur smoothly rather than jumping abruptly
+- **AND** behavior is consistent across supported breakpoints

openspec/changes/p08-seo-tweaks/specs/news-structured-data/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Homepage publishes Newspaper structured data
+The system SHALL expose a valid JSON-LD entity of type `Newspaper` on the homepage.
+
+#### Scenario: Newspaper entity is emitted on homepage
+- **WHEN** the homepage HTML is rendered
+- **THEN** a JSON-LD script block includes an entity with `@type` set to `Newspaper`
+- **AND** the entity includes stable publisher and site identity fields
+
+#### Scenario: Newspaper entity remains language-aware
+- **WHEN** homepage content is rendered in a selected language
+- **THEN** the structured data includes language context for the active locale
+- **AND** language output stays consistent with visible content language
+
+### Requirement: Each rendered news item publishes NewsArticle structured data
+The system SHALL expose a valid JSON-LD entity of type `NewsArticle` for each rendered news item in hero and feed contexts.
+
+#### Scenario: NewsArticle entities include required semantic fields
+- **WHEN** news items are present on the homepage
+- **THEN** each `NewsArticle` entity includes headline, description, image, publication dates, and URL fields
+- **AND** publisher and author context are present for each item
+
+#### Scenario: Structured data avoids duplicate article entities
+- **WHEN** article data appears across hero and feed sections
+- **THEN** structured-data output deduplicates entities for the same article URL
+- **AND** only one canonical semantic entry remains for each unique article

openspec/changes/p08-seo-tweaks/specs/seo-meta-and-social-tags/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Core SEO metadata is present on public pages
+The system SHALL expose standards-compliant SEO metadata on the homepage and policy pages, including description, robots, canonical URL, and social preview metadata.
+
+#### Scenario: Homepage metadata baseline exists
+- **WHEN** a crawler or browser loads the homepage
+- **THEN** the document includes `description`, `robots`, and canonical metadata
+- **AND** Open Graph and Twitter card metadata fields are present with non-empty values
+
+#### Scenario: Policy pages include indexable metadata
+- **WHEN** a crawler loads `/terms` or `/attribution`
+- **THEN** the page includes page-specific `title` and `description` metadata
+- **AND** Open Graph and Twitter card metadata are present for link previews
+
+### Requirement: Canonical and preview metadata remain deterministic
+The system SHALL keep canonical and preview metadata deterministic for each route to avoid conflicting crawler signals.
+
+#### Scenario: Canonical URL reflects active route
+- **WHEN** metadata is rendered for a public route
+- **THEN** exactly one canonical link is emitted for that route
+- **AND** canonical metadata does not point to unrelated routes
+
+#### Scenario: Social preview tags map to current page context
+- **WHEN** the page metadata is generated or updated
+- **THEN** `og:title`, `og:description`, and corresponding Twitter fields reflect the current page context
+- **AND** preview image fields resolve to a valid absolute URL