Perceived Responsiveness Related Requests Plan V1

Source Requests

related_feature_requests.txt lists:

• things that should be instant take too long

• clicking things in the menubar should be instant, not ~1 second

• clicking "post reply" should not take 2-3 seconds

• the "no css loaded yet" flag is annoying/disturbing

Are These Actually Related?

Yes, but only at the user-experience level.

They are all reports that the site feels unsettled or slow before it reaches the state the user expected. They should be addressed under one perceived-responsiveness effort so the fixes share measurement, acceptance thresholds, and production verification.

With the added goal of reaching "mostly offline-capable PWA app" status, the requests become more tightly related: the same static artifacts, immutable assets, prefetch hints, cache headers, and client-side route warming that make clicks feel instant are also the foundation for a read-mostly offline experience.

They are probably not one single code bug:

• Menubar clicks are plain navigation links in templates/partials/nav.php. If these take about one second, the likely causes are route/render/read-model/static-artifact/server latency, cache behavior, or full document navigation cost.

• Post reply is a signed write path. Existing plans already implemented optimistic inline replies in docs/plans/production_slow_actions_slice3_optimistic_reply_submit_plan_v1.md, so a current 2-3 second report probably means production is not on that path, the user is using a non-inline/anonymous fallback path, browser identity setup is still blocking first feedback, or success navigation/reload is the perceived slow part.

• The "no css loaded yet" complaint is a different class: asset loading and loading-state copy. There is no literal no css loaded yet string in the current PHP templates, but the repo contains many repeatedly fingerprinted asset files in public/assets, which points to static asset hygiene as a credible related investigation.

• Offline posting is not the same problem as instant posting. The first PWA slice should make already-viewed public pages and core assets available offline, while preserving normal online canonical writes. Offline write queuing should be a later explicit product decision because identity, approval, git commits, and conflict handling are authoritative server-side.

Existing Context

• production_slow_actions_client_responsiveness_plan_v1.md inventories slow-capable actions and recommends optimistic client behavior.

• production_slow_actions_slice2_optimistic_reactions_plan_v1.md is marked implemented for reaction clicks.

• production_slow_actions_slice3_optimistic_reply_submit_plan_v1.md is marked implemented for inline reply pending cards.

• production_slow_actions_slice5_identity_prewarm_prepare_plan_v1.md is marked implemented through quiet prewarm/no standalone prepare UI.

• production_instant_busy_page_simple_plan_v1.md covers fail-fast lock contention by setting FORUM_EXECUTION_LOCK_TIMEOUT_SECONDS=0.

• StaticArtifactBuilder::build() copies fingerprinted assets, and the current public/assets directory contains many already-fingerprinted copies with repeated hashes. That is not necessarily the reported CSS flag, but it is a concrete asset-loading risk.

• There is no current service worker or web app manifest in the searched app files. PWA support should therefore be introduced as a new, narrow layer rather than assumed to exist.

• The production deploy model already favors static HTML artifacts and immutable/versioned assets. That aligns well with both service-worker caching and older browser prefetch hints.

Solution Options

Option A: Measure First, Then Patch The Hot Path

Add or use existing browser/server timing around menu navigation, reply first feedback, reply success navigation, CSS first paint, and asset load failure.

Pros:

• Avoids guessing which path is actually slow in production.

• Can distinguish backend latency from first-click identity setup, full-page navigation, cache miss artifact builds, and CSS 404/mis-cache behavior.

• Fits the existing Server-Timing and opt-in browser timing work.

Cons:

• Does not immediately remove the annoyance.

• Requires production reproduction or debug capture.

Option B: Client-Side Perceived-Speed Fixes

Keep server behavior authoritative, but make the UI react immediately:

• Add pressed/loading state to nav links on click.

• Prefetch likely nav destinations after idle.

• Ensure inline reply shows pending feedback before waiting on the reply write.

• Keep the reply draft visible until confirmed.

• Hide transient identity-status messages once the actual action-specific pending state appears.

Pros:

• Directly addresses what the user sees.

• Low risk to canonical data.

• Builds on existing optimistic reply/reaction code.

Cons:

• Does not reduce actual backend latency.

• Navigation still replaces the full document unless a more ambitious partial navigation model is added.

Option C: Backend And Static-Artifact Speed Fixes

Reduce the amount of server work needed for common GET and write paths:

• Verify nav routes are served from static HTML where intended.

• Skip same-request static artifact generation when it would contend for locks.

• Make read-model freshness checks fail fast or run outside user-facing requests where possible.

• Keep reply writes on incremental read-model update, especially when labels are present.

• Confirm production uses FORUM_EXECUTION_LOCK_TIMEOUT_SECONDS=0 or another fail-fast contention setting.

Pros:

• Improves real latency, not only perceived latency.

• Helps all clients, including non-JavaScript fallback paths.

Cons:

• More operational and architectural risk.

• Requires careful production validation around stale read models and artifact freshness.

Option D: Asset Loading And CSS-State Hardening

Treat the CSS complaint as its own track:

• Find where "no css loaded yet" is emitted in production or static output.

• Remove alarming copy; if a CSS diagnostic is needed, make it operator-only or console-only.

• Stop recursive fingerprinting of already-fingerprinted assets.

• Clean generated fingerprint duplicates out of source/static asset directories.

• Add a smoke test that the rendered stylesheet URL resolves to HTTP 200 and is not a repeatedly fingerprinted filename.

Pros:

• Directly addresses the most disturbing visual symptom.

• Reduces chances of cache misses, large asset directories, and broken stylesheet references.

Cons:

• May not affect menubar or reply latency.

• Needs care to avoid deleting user/generated files blindly.

Option E: Partial Navigation Or App-Shell Navigation

Intercept same-site nav clicks, fetch page HTML or a fragment, swap the main content, and keep the shell/CSS/JS loaded.

Pros:

• Can make menubar navigation feel genuinely instant after the first load.

• Avoids full CSS/JS re-evaluation on every nav click.

Cons:

• Highest complexity.

• Needs history, focus, scroll, error, script lifecycle, static/dynamic route, and non-JavaScript fallback design.

• Premature unless simpler caching/prefetch/static-route fixes fail.

Option F: PWA Read Cache Plus Legacy Prefetch

Add a minimal PWA layer for modern browsers and a no-service-worker prefetch layer for older browsers:

• Add a web app manifest linked from the shared layout.

• Add a service worker that precaches the app shell essentials and runtime-caches visited public GET pages.

• Add a small offline fallback page for navigations not yet cached.

• Add <link rel="prefetch"> hints for top-level nav destinations and critical assets.

• Add JavaScript idle prefetch with fetch() where available, falling back to link hints only.

• Keep all normal links and forms functional without service worker, JavaScript prefetch, or PWA install support.

Pros:

• Makes instant navigation and offline-read support reinforce each other.

• Service workers help modern browsers; link prefetch/static artifacts help older browsers and no-JavaScript clients.

• Keeps canonical writes online-only for the first version.

• Reduces repeated CSS/JS loading concerns by explicitly caching immutable fingerprinted assets.

Cons:

• Requires careful cache invalidation so users do not get stuck on stale pages.

• Needs an app version/cache version contract.

• Offline behavior can mislead users unless write actions clearly require a connection.

• Some older browsers ignore prefetch, so static HTML and HTTP cache headers still matter.

Recommended Plan

Recommend a staged approach: Option A plus Option D first, then add Option F as the main strategic direction for "instant-feeling" navigation and mostly offline reads. Use targeted Option B/C fixes based on measurements. Defer Option E's app-shell/partial-navigation approach until the simpler PWA and prefetch layers prove insufficient.

The first offline target should be read-mostly:

• cached app shell assets

• cached public pages the user has visited

• cached top-level nav pages

• an offline fallback page

• online-only canonical writes with drafts preserved locally

Do not promise offline posting in this plan. Treat offline write queueing as a separate future plan.

Stage 1: Reproduce And Classify

Goal:

• Determine whether each report is active in the current code and where the delay occurs.

• Establish a baseline for both online speed and offline-read readiness.

Work:

• Test a local thread page with JavaScript enabled:

  • click each nav item and record click-to-first-paint and click-to-load.

  • submit an inline signed reply and record click-to-pending-card, click-to-response, and click-to-canonical-page.

  • submit from /compose/reply and anonymous reply paths to see if the reported delay is from fallback behavior.

• Enable existing debug_timing paths where available.

• Capture Server-Timing for menu GETs and reply APIs.

• Inspect the rendered stylesheet URL and confirm it resolves.

• Check whether the browser supports service workers, Cache Storage, web app manifests, and link prefetch on the target browser set.

• Define the minimum older-browser fallback target:

  • normal links keep working

  • static artifacts and HTTP cache headers still help

  • <link rel="prefetch"> may improve warm nav where supported

  • no core behavior depends on service workers

Acceptance:

• Each request is classified as one of: backend GET latency, backend write latency, identity-prep latency, success-navigation latency, asset/CSS load problem, or stale production deployment.

• The plan has a target browser matrix with modern PWA support, partial prefetch-only support, and baseline no-prefetch behavior.

Stage 2: CSS And Asset Hygiene

Goal:

• Remove the disturbing CSS-loading state and prevent stylesheet cache/path churn before adding any PWA cache layer.

Work:

• Locate the exact production source of "no css loaded yet"; check static artifacts in addition to PHP templates.

• Replace user-facing CSS diagnostic copy with no visible message, a quiet fallback style, or an operator-only diagnostic.

• Update asset fingerprint copying so it ignores already-fingerprinted asset filenames.

• Add cleanup guidance or a script for generated duplicate fingerprint files after confirming which files are source assets.

• Define cache classes:

  • immutable fingerprinted assets: long-lived cacheable

  • canonical source asset paths such as /assets/site.css: short-lived or redirected/resolved to fingerprinted paths

  • HTML pages: network-first or stale-while-revalidate, never immutable

  • API and write routes: no-store

• Add smoke coverage for:

  • stylesheet link matches one hash segment, for example /assets/site.<hash>.css

  • the linked asset maps back to /assets/site.css

  • static artifact build does not create site.<hash>.<hash>.css

  • PWA/service-worker asset manifests do not include recursively fingerprinted files

Acceptance:

• No normal page shows "no css loaded yet."

• Rendered stylesheet links resolve.

• Static build does not multiply fingerprint hashes.

• Asset paths are stable enough to be safely precached.

Stage 3: PWA Foundation

Goal:

• Add a minimal, read-mostly PWA layer without changing canonical write behavior.

Work:

• Add public/manifest.webmanifest with conservative app metadata, icons, theme color, start_url, and display.

• Link the manifest from templates/layout.php.

• Add public/offline.html as a small static fallback page using inline critical styling or the already-cached stylesheet.

• Add public/service_worker.js with an explicit version string based on app version or build hash.

• Register the service worker from a small deferred script loaded by the shared layout.

• Precaching should include only:

  • /

  • /about/

  • /users/

  • /tools/

  • /offline.html

  • current fingerprinted CSS and small first-party JS assets

  • favicon and manifest

• Runtime caching should include public same-origin GET HTML pages that are safe for anonymous viewing.

• Do not cache:

  • /api/*

  • POST responses

  • account/key pages with identity-sensitive state unless explicitly reviewed

  • pages requested with cookies if they contain personalized content

• Add an offline banner or understated status only when a navigation fails and the service worker serves cached/fallback content.

Acceptance:

• A modern browser can load the board once, go offline, reload the board, and see cached content or the offline fallback.

• Cached assets render with CSS; no "no css loaded yet" message appears offline.

• Write actions while offline fail clearly and preserve drafts where compose draft support already exists.

• API responses and signed/private state are not served stale from the service worker.

Stage 4: Menubar Navigation And Prefetch

Goal:

• Make top-level nav clicks feel immediate in modern browsers and improve warm navigation in older browsers where possible.

Work:

• Confirm whether /, /about/, /users/, /tools/, and /account/key/ are static, dynamic, or mixed in production.

• For static-safe public routes, prefer direct static artifacts and cacheable fingerprinted assets.

• Add lightweight click feedback to .nav-link for full-page navigations.

• Add declarative hints in the shared layout for stable public destinations:

  • <link rel="prefetch" href="/">

  • <link rel="prefetch" href="/about/">

  • <link rel="prefetch" href="/users/">

  • <link rel="prefetch" href="/tools/">

• Avoid prefetching identity/account pages unless reviewed for personalized state.

• Add an idle prefetch script for browsers with fetch, requestIdleCallback, or a timeout fallback:

  • only prefetch same-origin GET routes

  • only prefetch when the connection is not marked constrained where navigator.connection exists

  • do not prefetch when Save-Data is enabled

  • keep request count small

• Let the service worker populate its runtime cache from these prefetches in modern browsers.

• In older browsers, rely on link prefetch where supported and ordinary HTTP cache/static artifacts where not.

• If a route still takes about one second, use Server-Timing to identify read-model rebuild, stale marker, lock wait, template render, or artifact generation.

Acceptance:

• Nav click first feedback occurs within 100 ms.

• Cached/static nav destination reaches first contentful render within an agreed threshold, initially 300-500 ms on a warm connection.

• If backend work blocks the route, the response exposes timing enough to identify the blocking step.

• In a service-worker browser, revisiting prefetched nav destinations works from cache while offline.

• In a no-service-worker browser, nav still works normally and benefits from static artifacts/cache headers or link prefetch where supported.

Stage 5: Reply Submit

Goal:

• Make Post reply show meaningful feedback immediately and avoid a 2-3 second dead period.

Work:

• Verify current production includes the implemented optimistic inline reply flow.

• Confirm inline signed replies call /api/create_reply and render a pending card before the fetch resolves.

• Confirm anonymous replies and standalone /compose/reply are intentionally fallback paths; decide whether to add optimistic behavior there too.

• Measure first signed action separately from later signed actions to isolate identity setup.

• If the slow part is success navigation, consider in-place canonical reconciliation instead of navigating after success.

• If the slow part is server write time, apply backend fixes from Stage 6 while preserving pending UI.

• For offline/PWA behavior:

  • do not attempt canonical reply submission while offline in the first version

  • detect offline before signed submit when possible

  • keep the draft available and show a clear online-required message

  • consider storing an explicit local draft marker, not a hidden outbox, if the user tried to submit offline

Acceptance:

• Inline signed reply first visible feedback appears within 100 ms after identity readiness.

• A fresh identity setup shows clear user-initiated progress rather than silence.

• Failed replies keep the draft recoverable.

• Success does not leave duplicate pending/canonical reply cards.

• Offline reply attempts do not appear posted and do not lose text.

Stage 6: Backend Contention And Real Latency

Goal:

• Reduce actual server wait time where measurement shows backend delay.

Work:

• Confirm production lock timeout policy and whether busy pages fail fast.

• Audit reply writes for incremental read-model update fallback cases.

• Skip or defer best-effort static artifact generation when it would extend a user response.

• Add or tighten timing buckets for git commit, read-model update, artifact invalidation, and static artifact generation.

Acceptance:

• Reply API timing identifies git, read-model, lock, and artifact components.

• Common reply writes avoid full read-model rebuilds.

• Lock contention returns a clear immediate busy response rather than a silent stall.

Stage 7: PWA Verification And Release Guardrails

Goal:

• Keep the PWA layer from making freshness, privacy, or offline-write semantics worse.

Work:

• Add smoke tests or Playwright checks for:

  • manifest link exists and resolves

  • service worker script resolves with JavaScript content type

  • offline fallback exists

  • fingerprinted CSS is in the precache list exactly once

  • /api/version, /api/create_reply, and other API routes are not cached as offline successes

  • service-worker cache version changes when app assets change

• Add a runbook note for clearing/rotating service-worker caches after deploys.

• Add a manual test matrix:

  • modern Chromium/Firefox/Safari with service worker

  • browser with service worker disabled

  • older browser with only normal links/cache

  • slow connection with Save-Data or constrained network settings where available

Acceptance:

• Modern browser passes install/offline-read smoke checks.

• Older browser still gets normal static/public pages and no broken PWA-only dependency.

• A deploy can invalidate stale service-worker caches predictably.

Non-Goals

• Do not weaken canonical write, identity, approval, or git-history guarantees.

• Do not remove non-JavaScript compose/reply fallbacks.

• Do not convert the site to a single-page app in the first pass.

• Do not delete generated asset files until the source/generated boundary is confirmed.

• Do not implement offline canonical posting in this plan.

• Do not cache authenticated, identity-sensitive, or approval-sensitive responses without a separate privacy review.

Open Questions

• Is the "no css loaded yet" flag from current production HTML, old static artifacts, browser extension/debug tooling, or a page not represented by the PHP templates?

• Is the reported Post reply path inline signed reply, standalone signed reply, or anonymous reply?

• Are menubar clicks slow on all routes or only routes that enter PHP/read-model work?

• Should standalone /compose/reply get optimistic API submission, or is canonical redirect acceptable there?

• What production latency target should count as "instant" for warm nav and signed writes?

• Which browsers are specifically meant by "older browsers," and do they support <link rel="prefetch">, only normal HTTP caching, or neither?

• Should the PWA install prompt/manifest use the forum brand only, or expose a more app-like short name?

• Should cached offline pages show their last-updated time?

• How aggressive should prefetch be on metered or slow connections?

• Is /account/key/ allowed to be cached as an app shell page, or should all account/identity surfaces remain network-only?