Why

The first universal-reader performance release reduced repeated reads, but two visible costs remain. After the ten-minute transformed cache expires, a reader still waits for synchronous GitHub revalidation. A cold issue page waits for its below-the-fold discussion before returning the title and body. Mermaid pages also download a 3.45 MB raw / roughly 906 KB compressed monolith even when they use one diagram type.

Production evidence on 2026-08-25 showed hot reader pages around 0.27-0.39 seconds, expired-cache reads around 0.75 seconds, common cold issues around 0.85 seconds, and one 2.1-second upstream outlier. The performance contract should keep safe cached content immediately readable, make discussion progressive, and load only the diagram code a page uses.

What

In scope:

• Serve a recent last-safe transformed representation immediately while revalidating GitHub in waitUntil.
• Keep hard-age and missing/private deletion bounds so background refresh cannot turn into indefinite mirroring.
• Render issue metadata and body without waiting for comments; hydrate sanitized discussion from a same-origin fragment endpoint.
• Add an accessible loading/error/retry state that preserves the Issue Dispatch visual language.
• Prefetch a repository issue only after deliberate hover or keyboard focus.
• Split Mermaid by diagram type while retaining all currently supported Mermaid formats.
• Back canonical article polling off from 15 to 30 to 60 seconds after unchanged responses.

Out of scope:

• Privileged GitHub credentials, private repositories, arbitrary-repository D1 writes, a new Cloudflare storage product, WebSockets, or Durable Objects.
• Prefetching every issue card or executing unsanitized client-rendered Markdown.
• Replacing the established visual system.

Design

sequenceDiagram
  participant B as Browser
  participant W as IssuePages Worker
  participant C as Local/tiered cache
  participant G as GitHub
  B->>W: Open issue
  W->>C: Read transformed issue
  alt fresh or soft-stale
    C-->>W: Safe issue
    W-->>B: Article body immediately
    W-->>G: Background revalidation when soft-stale
  else cold
    W->>G: Fetch issue
    G-->>W: Issue JSON/HTML
    W-->>B: Article body
  end
  B->>W: Load discussion fragment
  W->>C: Read/fetch sanitized comments
  W-->>B: Replace reserved discussion state

The discussion placeholder is a fixed reading-pane region below the article body with aria-live=polite. Zero-comment issues render their final empty state without JavaScript or a comments request. Comment fragments are produced only by the existing server sanitizer and inserted from the same origin. Hover/focus prefetch uses a short intent delay and deduplicates URLs.

Mermaid remains conditional at the page level. The entry and diagram implementations are emitted as ESM chunks so flowchart, sequence, class, and other formats download only their shared runtime plus the selected diagram module.

Specs

Requirement: Immediate safe cache reads

IssuePages SHALL serve a recent safe transformed cache entry immediately and revalidate it after the response.

Scenario: Soft-freshness window expired

• WHEN a valid last-safe cache entry is younger than the background-refresh ceiling
• THEN the page renders immediately with a refreshing cache state and GitHub revalidation runs through waitUntil

Scenario: Background refresh finds missing content

• WHEN GitHub returns a definitive missing/private response
• THEN local fresh and stale representations are removed for the next request

Requirement: Progressive discussion

IssuePages SHALL not block issue title/body delivery on comments.

Scenario: Issue has comments

• WHEN the article body renders
• THEN an accessible reserved discussion state requests a sanitized same-origin fragment and replaces itself without shifting content above it

Scenario: Issue has no comments

• WHEN GitHub reports zero comments
• THEN the final empty state renders immediately and no discussion request is made

Scenario: Discussion fails

• WHEN the fragment request fails
• THEN the article remains readable and the discussion region offers a retry and original-GitHub recovery path

Requirement: Bounded intent prefetch

IssuePages SHALL prefetch only links for which a reader signals intent.

Scenario: Pointer or keyboard intent

• WHEN an issue link remains hovered briefly or receives focus
• THEN one same-origin prefetch is scheduled for that exact URL

Requirement: Diagram-specific delivery

Mermaid pages SHALL preserve supported diagram rendering without shipping every diagram implementation in one initial bundle.

Scenario: Page contains a flowchart

• WHEN Mermaid initializes
• THEN the shared entry and flowchart dependency chunks load while unrelated diagram chunks remain unloaded

Requirement: Adaptive canonical polling

Visible canonical articles SHALL reduce polling frequency after unchanged checks and reset to the fast interval after visibility or version activity.

Tasks

• 1. Implement soft-stale background revalidation, cache-state headers, deletion, and tests.
• 2. Split issue and discussion services; add sanitized fragment routes and recovery behavior.
• 3. Add the preserve-mode loading state, discussion client, intent prefetch, and adaptive polling.
• 4. Split Mermaid output and prove common diagram transfer reduction without format loss.
• 5. Run security, accessibility, responsive browser, detector, design-receipt, test, build, and startup checks.
• 6. Update durable documentation, commit, push, obtain green current-SHA CI, deploy exact SHA, and measure production.