clawfort/openspec/specs/article-permalinks-and-deep-link-modal/spec.md

Purpose

Canonical specification for article-permalinks-and-deep-link-modal requirements synced from OpenSpec change deltas.

Requirements

Requirement: Each news item exposes a permalink

The system SHALL expose a stable, shareable permalink for each rendered news item.

Scenario: Per-item permalink rendering

• WHEN a news item is rendered in hero or feed context
• THEN the UI provides a permalink target tied to that article context

Scenario: Permalink copy/share usability

• WHEN a user uses share/copy affordances for an item
• THEN the resulting URL contains sufficient information to resolve that article on load

Requirement: Deep-link loads article modal in open state

The system SHALL open the matching article modal when the page is loaded with a valid article permalink, regardless of whether the target is hero or feed content.

Scenario: Valid permalink opens modal

• WHEN a user lands on homepage with a permalink for an existing article
• THEN the corresponding article modal is opened automatically
• AND modal content matches the permalink target

Scenario: Hero permalink opens parity modal

• WHEN a user lands with a permalink for the current hero article
• THEN the modal opens with the same structure and behaviors as feed-opened modal
• AND summary image render path is executed normally

Scenario: Escape closes deep-linked modal

• WHEN a modal opened from permalink is focused
• THEN pressing Escape closes the modal
• AND URL deep-link state is cleared consistently

Scenario: Invalid permalink fails safely

• WHEN permalink article id does not resolve to an existing item
• THEN modal is not opened
• AND main page remains fully usable