bulk commit changes!

openspec/changes/archive/2026-02-13-p10-ui-fixes/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-13

openspec/changes/archive/2026-02-13-p10-ui-fixes/design.md

@@ -0,0 +1,88 @@
+## Context
+
+`frontend/index.html` currently renders the hero CTA as an external redirect (`window.open(item.source_url)`), and modal sizing is constrained by `max-w-2xl` with `max-h-[90vh]`. TL;DR content does not expose a dedicated loading placeholder, and hero badges can lose readability over bright images. On the backend, `backend/news_service.py` already performs keyword extraction and provider fallback, but defaults remain too generic (`"news technology"`) and do not explicitly prioritize AI-topic fallback behavior.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Keep users on-site by making the hero primary CTA open the existing TL;DR modal flow.
+- Ensure `LATEST` and relative timestamp remain legible over all hero images in light/dark themes.
+- Increase modal usable area (width and near-full-height scrolling behavior) without breaking mobile usability.
+- Add a small horizontal shimmer placeholder for TL;DR bullets while modal content initializes.
+- Improve image relevance with stronger AI-focused keyword fallback and deterministic generic AI-image fallback when lookup fails.
+
+**Non-Goals:**
+- Rebuilding the full feed card architecture.
+- Replacing existing provider integrations or adding new third-party image providers.
+- Introducing backend sentiment ML models.
+- Reworking scheduler or ingestion cadence.
+
+## Decisions
+
+### Decision: Reuse existing modal interaction path for hero CTA
+**Decision:** Wire hero CTA to the same `openSummary(item)` behavior used by feed cards.
+
+**Rationale:**
+- Reuses existing event tracking and modal rendering logic.
+- Avoids duplicate interaction models and reduces regression risk.
+
+**Alternatives considered:**
+- Add a second hero-only modal implementation: rejected due to duplicate UI state and maintenance cost.
+
+### Decision: Enforce readability with layered overlay + contrast-safe tokens
+**Decision:** Strengthen hero overlay and badge/text color tokens so metadata remains visible independent of image luminance.
+
+**Rationale:**
+- Solves visibility issues without image preprocessing.
+- Keeps responsive behavior in CSS instead of JS image analysis.
+
+**Alternatives considered:**
+- Dynamic luminance detection per image: rejected as unnecessary complexity for current scope.
+
+### Decision: Expand modal dimensions with responsive constraints
+**Decision:** Use a wider desktop container (minimum half viewport intent) while preserving mobile full-width behavior and near-full-height scrolling.
+
+**Rationale:**
+- Improves readability for summary blocks and TL;DR bullets.
+- Keeps accessibility of close controls and keyboard escape path.
+
+**Alternatives considered:**
+- Full-screen modal only: rejected due to excessive visual disruption on desktop.
+
+### Decision: Treat TL;DR loading as explicit skeleton state
+**Decision:** Add a low-height horizontal shimmer placeholder visible when TL;DR is not yet available.
+
+**Rationale:**
+- Reduces perceived latency ambiguity.
+- Matches existing skeleton design language already used for images/cards.
+
+### Decision: Improve fallback query semantics for AI-news image retrieval
+**Decision:** Enhance keyword fallback to AI-focused defaults (`ai machine learning deep learning`) and add explicit generic AI image fallback contract.
+
+**Rationale:**
+- Reduces irrelevant imagery when topic extraction is weak or providers return noisy results.
+- Keeps behavior deterministic and testable.
+
+## Risks / Trade-offs
+
+- **[Risk] Wider modal may crowd smaller laptops** -> Mitigation: use responsive width caps with mobile-first breakpoints and overflow handling.
+- **[Risk] Hero overlay could darken images too much** -> Mitigation: tune gradient opacity and preserve theme-specific token overrides.
+- **[Risk] Fallback image monotony if providers fail frequently** -> Mitigation: keep provider chain first; generic AI fallback only as terminal fallback.
+- **[Trade-off] Stronger AI default keywords may reduce non-AI niche relevance** -> Mitigation: apply defaults only when extracted keywords are insufficient.
+
+## Migration Plan
+
+1. Update hero CTA and hero readability styles in `frontend/index.html`.
+2. Update modal sizing and TL;DR shimmer loading state in `frontend/index.html`.
+3. Update backend keyword fallback and generic AI image fallback behavior in `backend/news_service.py`.
+4. Verify behavior manually on desktop/mobile and run relevant checks.
+
+Rollback:
+- Revert hero CTA to external link behavior.
+- Revert modal class and shimmer additions.
+- Revert keyword/default fallback updates in image pipeline.
+
+## Open Questions
+
+- Should generic AI fallback be local static asset only, or deterministic remote URL with local optimization?
+- Do we need separate fallback keyword sets per language now, or keep English-focused defaults in this change?

openspec/changes/archive/2026-02-13-p10-ui-fixes/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+The current UX for the homepage hero and summary modal still has high-friction behavior and readability issues, and image relevance is still inconsistent for AI news topics. Fixing these now improves retention, trust, and content quality without changing the core product flow.
+
+## What Changes
+
+- Change hero primary CTA behavior to open the in-site TL;DR summary flow instead of immediately sending users off-site.
+- Improve hero readability over images so `LATEST` and relative time metadata remain visible across themes and screen sizes.
+- Increase modal width and adjust modal height behavior so long content can use near full-height viewport scrolling.
+- Add a short horizontal shimmer placeholder for TL;DR bullet content while summary details are loading.
+- Strengthen image relevance by extracting better keywords from news text, adding AI-topic default keywords, and using a generic AI fallback image when providers fail.
+
+## Capabilities
+
+### New Capabilities
+- `hero-summary-entry-and-readability`: Define hero CTA in-site summary entry behavior and image-overlay readability requirements for badges, timestamps, headline, and summary text.
+- `modal-layout-and-loading-feedback`: Define modal sizing/overflow behavior and TL;DR loading placeholders for clearer perceived loading state.
+- `news-image-relevance-and-fallbacks`: Define keyword extraction quality, default AI keyword fallback rules, and generic AI image fallback behavior when no relevant image is found.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- **Frontend/UI:** `frontend/index.html` (hero CTA wiring, hero overlay/readability styles, modal width/height classes, TL;DR loading skeleton state).
+- **Backend/Image Pipeline:** `backend/news_service.py` (keyword extraction and provider fallback behavior for summary images).
+- **Assets/Config:** generic AI fallback image path/asset contract and related docs may be updated.

openspec/changes/archive/2026-02-13-p10-ui-fixes/specs/hero-summary-entry-and-readability/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Hero primary action opens in-site TL;DR summary
+The homepage hero primary CTA SHALL open the in-site summary modal for the hero article instead of navigating off-site.
+
+#### Scenario: Hero CTA opens summary modal
+- **WHEN** a user clicks the hero primary CTA
+- **THEN** the system opens the summary modal for the current hero article
+- **AND** no external navigation is triggered by that CTA
+
+### Requirement: Hero source link remains available as secondary action
+The hero section SHALL keep an explicit secondary source-link action for external navigation.
+
+#### Scenario: Source link navigates externally
+- **WHEN** a user clicks the hero source link
+- **THEN** the system opens the article source URL in a new tab
+
+### Requirement: Hero metadata readability over images
+Hero metadata (`LATEST`, relative time, headline, and summary) SHALL remain visually legible across bright and dark images on desktop and mobile.
+
+#### Scenario: Bright image background
+- **WHEN** the hero image contains bright regions under metadata text
+- **THEN** overlay and text styles preserve readable contrast for metadata and headline blocks
+
+#### Scenario: Mobile viewport readability
+- **WHEN** the hero renders on a mobile viewport
+- **THEN** metadata and title remain readable without overlapping controls or clipping

openspec/changes/archive/2026-02-13-p10-ui-fixes/specs/modal-layout-and-loading-feedback/spec.md

@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### Requirement: Modal width supports comfortable desktop reading
+The summary modal SHALL render with a desktop width that is approximately half of viewport width or larger when space allows, while remaining responsive on small screens.
+
+#### Scenario: Desktop width expansion
+- **WHEN** the modal opens on desktop viewport widths
+- **THEN** the modal content area renders wider than the previous narrow baseline
+- **AND** text blocks are readable without excessive line wrapping
+
+#### Scenario: Mobile responsiveness
+- **WHEN** the modal opens on small mobile viewport widths
+- **THEN** modal width remains fully usable without horizontal overflow
+
+### Requirement: Modal height supports near-full viewport scrolling
+The summary modal SHALL use near full-height viewport behavior when content overflows.
+
+#### Scenario: Overflowing summary content
+- **WHEN** summary content exceeds modal viewport height
+- **THEN** modal body remains scrollable with close controls accessible
+- **AND** modal container uses near full viewport height constraints
+
+### Requirement: TL;DR loading placeholder is explicit
+The modal SHALL show a horizontal shimmer placeholder for TL;DR content while TL;DR bullets are not yet available.
+
+#### Scenario: TL;DR pending state
+- **WHEN** the summary modal is open and TL;DR bullet data is pending
+- **THEN** the system displays a low-height horizontal shimmer placeholder
+
+#### Scenario: TL;DR loaded state
+- **WHEN** TL;DR bullet data becomes available
+- **THEN** shimmer placeholder is removed
+- **AND** TL;DR bullet list is rendered

openspec/changes/archive/2026-02-13-p10-ui-fixes/specs/news-image-relevance-and-fallbacks/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Image query fallback uses AI-focused defaults
+When extracted image keywords are insufficient, the system SHALL use AI-focused default fallback terms.
+
+#### Scenario: Empty keyword extraction
+- **WHEN** keyword extraction yields no usable topic keywords
+- **THEN** the system uses default fallback terms including AI-domain keywords (for example `ai`, `machine learning`, `deep learning`)
+
+### Requirement: Generic AI image fallback is guaranteed
+If provider lookups fail to return a usable summary image, the system SHALL use a generic AI-themed fallback image.
+
+#### Scenario: Provider chain failure
+- **WHEN** all configured image providers return no usable image
+- **THEN** the system assigns a generic AI fallback image URL/path for summary image
+
+### Requirement: Fallback behavior remains context-aware first
+The system SHALL attempt context-aware keyword retrieval before any generic fallback image is selected.
+
+#### Scenario: Context-aware attempt precedes fallback
+- **WHEN** summary image selection runs for a news item
+- **THEN** the system first attempts provider queries from extracted context-aware keywords
+- **AND** only falls back to generic AI image if these attempts fail

openspec/changes/archive/2026-02-13-p10-ui-fixes/tasks.md

@@ -0,0 +1,29 @@
+## 1. Hero UX Fixes
+
+- [x] 1.1 Update hero primary CTA in `frontend/index.html` to open the in-site summary modal for the hero item.
+- [x] 1.2 Keep hero source link as a secondary external action and preserve tracking events.
+- [x] 1.3 Strengthen hero overlay and metadata styles so `LATEST` and relative time remain readable across image brightness levels.
+
+## 2. Modal Layout Improvements
+
+- [x] 2.1 Increase modal width for desktop while keeping mobile-safe responsive behavior.
+- [x] 2.2 Update modal height/overflow behavior to support near full-height scrolling for long content.
+- [x] 2.3 Verify close controls and keyboard escape behavior remain intact after sizing changes.
+
+## 3. TL;DR Loading Feedback
+
+- [x] 3.1 Add a dedicated horizontal shimmer placeholder for TL;DR content while modal summary data is initializing.
+- [x] 3.2 Hide the TL;DR shimmer placeholder when TL;DR bullets are available and render the bullet list.
+
+## 4. Image Relevance and Fallback
+
+- [x] 4.1 Update keyword fallback logic in `backend/news_service.py` to use AI-focused default terms when extracted keywords are insufficient.
+- [x] 4.2 Add explicit generic AI summary-image fallback behavior when provider chain returns no usable image.
+- [x] 4.3 Ensure context-aware keyword/provider attempts always run before generic AI fallback selection.
+
+## 5. Validation
+
+- [x] 5.1 Verify hero CTA opens summary modal instead of navigating away.
+- [x] 5.2 Verify modal sizing on desktop/mobile and long-content scrolling behavior.
+- [x] 5.3 Verify TL;DR shimmer appears during pending state and disappears after load.
+- [x] 5.4 Verify generic AI fallback image is used when provider chain fails.