pwa(capabilities): establish progressive-enhancement registry, browser support tiers & runtime diagnostics

[qnbs]

Parent

Part of #478 — PWA first-class excellence/hardening.

Why this is foundational

The new PWA excellence program deliberately allows browser-native features to exceed native behavior. That only remains maintainable if capability decisions are centralized and truthful.

Without a capability registry, advanced APIs tend to produce scattered checks such as if ('gpu' in navigator) and inconsistent UX. This issue establishes one typed PWA capability/admission layer that all enhancement issues can consume.

Scope

Cover capabilities needed by #480–#488 and future PWA work, including where relevant:

• installed/standalone display mode;
• Service Worker/control/update state;
• Web Locks;
• BroadcastChannel;
• IndexedDB;
• OPFS;
• StorageManager estimate/persistence;
• File System Access;
• installed-PWA file handling / launch queue;
• Web Share / Share Target;
• protocol/launch handling;
• Window Controls Overlay;
• Badging;
• Notifications;
• Background Sync/deferred work;
• WebGPU;
• WASM acceleration primitives actually used by WorldScript;
• VisualViewport / Virtual Keyboard;
• Screen Wake Lock;
• network/local-network constraints relevant to Ollama;
• browser/device features needed by existing voice/media functionality.

Do not use a boolean-only model

A useful capability often has more states than supported/unsupported.

Suggested shape:

UNAVAILABLE
AVAILABLE
AVAILABLE_WITH_LIMITATIONS
PERMISSION_REQUIRED
PERMISSION_GRANTED
PERMISSION_DENIED
BROKEN_OR_FAILED_PROBE
DISABLED_BY_POLICY

Some features need richer structured details (WebGPU limits, storage estimate, display mode, permission state). Keep those typed.

Feature detection, not browser sniffing

Runtime behavior must primarily use feature/probe results.

Browser/version identification may be recorded for diagnostics/support matrices, but should not become the main feature gate unless a documented browser defect requires a scoped workaround.

Capability registry API

Provide a stable PWA-only abstraction, conceptually:

getPwaCapabilities(): PwaCapabilities
subscribePwaCapabilityChanges(...)
probeCapability(name, options?)
explainCapability(name): CapabilityExplanation

Do not put browser APIs into shared native/domain contracts.

Admission vs availability

Distinguish:

• API exists;
• API can initialize;
• product has admitted it for this workflow.

Example: navigator.gpu may exist but adapter/device acquisition or model limits may make a specific local-AI model inadmissible.

Likewise File System Access existing does not mean permission is currently granted.

User-facing diagnostics

Add an optional PWA Capabilities / Diagnostics panel with privacy-safe information:

Install mode: browser / standalone
Offline shell: ready / not controlled / update waiting
Storage persistence: granted / not granted / unavailable
Approx storage: used / quota (if exposed)
Local file access: supported / unsupported
WebGPU: ready / unavailable / initialization failed
Multi-tab coordination: full / degraded
Share target: supported / deployment dependent
Mobile keyboard enhancements: available / fallback

Include a copyable diagnostics summary that excludes:

• manuscript/project text;
• API keys/tokens;
• private file paths;
• encryption material;
• raw provider payloads.

This should dramatically improve future user reports like #266/#332/#341 without requesting giant console dumps.

Support tiers

Maintain a living browser support matrix driven by product evidence:

SUPPORTED
SUPPORTED_WITH_LIMITATIONS
BEST_EFFORT
UNSUPPORTED

At minimum consider current:

• Chrome/Chromium desktop;
• Edge desktop;
• Firefox desktop;
• Safari macOS;
• Android Chromium;
• iOS/iPadOS Safari installed/browser mode.

Do not claim a tier merely because MDN/caniuse says an API exists; WorldScript workflows need evidence.

Progressive enhancement contract

Every PWA-only enhancement must declare:

1. capability/probe required;
2. permission required, if any;
3. fallback path;
4. whether fallback preserves full semantics or reduced capability;
5. test environments;
6. privacy/security implications.

This prevents a Chromium-only feature from accidentally breaking baseline PWA behavior elsewhere.

CI

Where practical:

• unit-test capability normalization;
• browser E2E verifies key probes in supported engines;
• manifest capability declarations are checked against actual product handlers/tests;
• unsupported APIs are mocked/disabled to prove fallback;
• capability registry has no top-level import crashes in SSR/test/non-browser contexts.

Acceptance criteria

• One typed PWA capability/admission registry exists.
• New PWA enhancement code does not scatter raw feature checks throughout domain/UI code.
• Availability, permission and product admission are distinct.
• Privacy-safe user diagnostics exist.
• Browser support tiers are evidence-backed and documented.
• Every advanced PWA feature has an explicit fallback/degradation contract.
• Capability probing cannot crash baseline browser/native/test environments.
• Manifest declarations are reconciled with actual runtime handlers.

Non-goals

• UA-sniffing as architecture;
• pretending all browsers are equivalent;
• exposing fingerprinting-heavy diagnostics unnecessarily;
• leaking browser APIs into Qt/Rust Core contracts;
• blocking useful Chromium-native enhancements solely for lowest-common-denominator parity.

[qnbs]

Architecture refinement / existing-seed reconciliation — 2026-08-24

Treat this issue as a PWA capability aggregation/admission facade, not a new low-level detection stack.

Existing probes/authorities to compose before writing new probes

• services/ai/localAiDeviceProfiler.ts — WebGPU/WebNN/DirectML/compute/memory/battery/platform profile;
• services/ai/webGpuDetectorService.ts — existing WebGPU detail detection;
• services/storage/protectedWriteAdmission.ts — Web Locks capability already exercised in a security-critical path;
• packages/ai-core/src/tabLeaderElection.ts — BroadcastChannel/heartbeat coordination seed;
• workers/v2/duckdb.worker.ts — real OPFS capability/fallback seed;
• register-sw.ts / window.worldScriptPWA — SW/install/update state seed;
• features/featureCatalog.ts — product feature/maturity truth, which this issue must not replace;
• existing diagnostics/redaction paths for privacy-safe support output.

Four planes must remain distinct

1. Product feature plane
   featureCatalog / feature flags

2. Runtime capability plane
   PWA capability facade (#489)

3. Subsystem admission plane
   AI / storage / update / file workflow decides whether a capability
   is usable for the concrete task

4. Diagnostics/support plane
   privacy-safe composed explanation

Do not centralize subsystem policy merely because detection is centralized.

Implementation rule

Prefer adapters around existing probes. If two existing probes materially duplicate low-level browser detection, extract only the genuinely shared primitive and migrate callers deliberately; do not leave old and new detection paths permanently competing.

Acceptance additions

• Existing probes are inventoried before new ones are added.
• Feature flags/catalog remain product-admission truth; runtime capability does not override them.
• Workflow-specific admission remains owned by the subsystem.
• A failed capability probe is distinguishable from API absence and from product-policy disablement.
• Any duplicated probe replaced by pwa(capabilities): establish progressive-enhancement registry, browser support tiers & runtime diagnostics #489 has an explicit migration/deprecation plan.
• Diagnostics expose bounded facts and avoid unnecessary fingerprinting detail.