PWA Capability, Offline, Push & Camera Limits

First question: “PWA-ready” for which capability?

A team has a manifest and a registered service worker, so it declares the product “PWA-ready.” On real target devices, push permission may be denied, cached business data may be stale after a schema change, or the camera API may exist while permission/device state prevents capture. The failure is collapsing distinct capabilities into one label.

This lesson builds PWA Capability & Offline Readiness Matrix v1. Install, offline, push, and camera are separate contracts. Each records platform context, runtime detection, permission/lifecycle state, failure state, fallback, and evidence. READY is earned only from sufficient evidence; otherwise preserve PARTIAL, FALLBACK, UNSUPPORTED, or HOLD.

Lesson boundary

COM-036 owns PWA capability and readiness evidence. It does not decide whether the venture should build native; COM-037 owns that decision. COM-035 owns end-customer notification/minimal-PII policy.

Three hard boundaries:

1. API presence is not usable capability.
2. A manifest or service worker is not whole-PWA readiness.
3. A verdict from one browser/OS cannot be copied to a second platform.

Mental model: Need → Probe → State → Contract → Fallback → Decision

Core flow:

workflow need → per-capability probe → permission/lifecycle state → offline/cache contract → positive + negative fixture → READY | PARTIAL | FALLBACK | UNSUPPORTED | HOLD

Ask independently: is the required install/launch surface available? Is offline data allowed and version-safe? Are push permission and subscription active? Are camera permission and device state sufficient for capture?

Keep FACT, INFERENCE, and DESIGN separate

FACT — Manifest. The W3C manifest is JSON metadata for a web application, and user agents can impose their own conditions around capabilities. manifest_present=true is not universal install parity.

FACT — Service Worker. Service workers can receive events, influence fetch handling, and support offline-enabled applications. They do not automatically make arbitrary business state safe across schema changes, retention policy, or conflicts.

FACT — Push. Push permission and subscription are runtime concepts; subscriptions can refresh or deactivate. API availability is not an active subscription.

FACT — Camera. getUserMedia() is permission- and constraint-driven. API availability is not permission, device availability, or successful capture.

INFERENCE. Because these capabilities use different mechanisms and states, readiness should be evidenced capability by capability.

DESIGN — MAKNOW. The matrix fields, typed readiness states, fallback gates, and fail-closed rules are local design choices.

The 24-field readiness contract

The working record has twenty-four fields:

surface_id, capability_id, platform_family, user_agent_context, secure_context, manifest_present, manifest_scope, install_surface, service_worker_registration, service_worker_state, offline_data_class, cache_strategy, cache_version, network_state, push_api_available, push_permission_state, push_subscription_state, camera_api_available, camera_permission_state, camera_device_state, fallback_path, unsupported_reason, test_fixture, evidence_ref.

Gate 1 — State surface and platform before capability

mobile-web, home-screen-web-app, and desktop-browser are not one runtime context. Capture platform_family and user_agent_context in evidence.

Gate 2 — Make secure context explicit

Do not assume powerful capabilities in an insecure context. If a security prerequisite is missing, do not guess READY.

Gate 3 — Separate install from manifest

manifest_present, manifest_scope, and install_surface are different observations. Install/home-screen behavior can vary by user agent and version. Evidence describes the target platform—not a marketing definition of PWA.

Gate 4 — Offline is more than “we cache”

Ask which offline_data_class is allowed, which cache_strategy applies, and whether cache_version matches the current schema/data contract. After a schema migration, stale offline data can be more dangerous than an explicit online failure.

Gate 5 — Observe service-worker lifecycle

REGISTERED, INSTALLING, ACTIVATING, ACTIVE, and REDUNDANT are not equivalent. A transitional state is not full success when the workflow depends on offline behavior.

Gate 6 — Push = API + permission + subscription

Keep the three fields separate. push_api_available=true with push_permission_state=DENIED or push_subscription_state=NONE is not ready push.

Gate 7 — Camera = API + permission + device

camera_api_available=true is insufficient. Permission can be denied and a usable device can be absent. Predefine fallbacks such as file upload or manual code entry.

Gate 8 — Make fallback a business contract

A fallback is not merely “show an error.” It preserves an outcome: push→in-app inbox/email; camera→manual entry; offline→clearly marked read-only snapshot plus sync after reconnect.

Gate 9 — Require unsupported reason and evidence

Typed causes such as PERMISSION_DENIED, NO_DEVICE, NO_INSTALL_SURFACE, STALE_CACHE, or UNSUPPORTED_API make debugging auditable. Without provenance, teams guess.

Gate 10 — READY is the narrowest success state, not the default

If decisive evidence is UNKNOWN, DISPUTED, or STALE, use HOLD. Transitional support can be PARTIAL. If the primary path fails but an acceptable fallback preserves the outcome, use FALLBACK. If a required capability is known unavailable and no acceptable fallback exists, use UNSUPPORTED.

Worked examples

1. All four capabilities evidenced → READY

The target surface is secure; an install surface is observed; the service worker is ACTIVE; cache version matches the data contract; push permission is GRANTED with an ACTIVE subscription; camera permission and device are present. READY is defensible.

2. Push denied with operational fallback → FALLBACK

Order status must reach the user. The Push API exists but the user denies permission. A verified in-app inbox plus email preserves the workflow. This is FALLBACK, not READY and not the false statement “push works.”

3. Cache stale after schema change → HOLD

The service worker is active, but cache_version=v7 while the current data contract is v8. Offline correctness is not proven, so hold until migration/invalidation behavior is explicit.

4. Camera API present, device absent → UNSUPPORTED

Permission was granted but the target kiosk has no usable camera device and no approved fallback. The required capability is UNSUPPORTED.

Common failure modes

• Manifest theater: treat a manifest file as a completion badge.
• Service-worker magic: assume registration makes all state offline-safe.
• Cache forever: schema changes while cache version/invalidation does not.
• Push optimism: conflate API support, permission, and subscription.
• Camera optimism: conflate getUserMedia with permission/device/capture success.
• Browser-name detection: inspect a browser label instead of runtime capability/state.
• Silent fallback: degraded mode exists but users cannot see stale or reduced behavior.
• Copied verdict: reuse platform A’s verdict on platform B.
• Forced green: convert UNKNOWN/STALE into READY under release pressure.

Alternatives and trade-offs

Network-first favors freshness but weakens offline resilience.

Cache-first is strong for immutable assets but risky for business data without version/expiry semantics.

Stale-while-revalidate reduces latency but requires a data class that permits stale reads and UI that exposes freshness.

Push fallbacks such as inbox/email preserve continuity, but latency and attention semantics differ; do not describe them as equivalent push.

Camera fallbacks such as upload/manual entry improve availability but change UX and error rates.

Choose strategy from data class and business requirement, not from a fashionable snippet.

Experienced bridge: review questions

1. What exact target surface and platform are we testing?
2. Which capability is actually required?
3. What does the runtime probe show?
4. What are permission and lifecycle states?
5. Which offline data class is involved, and are stale reads allowed?
6. How is cache version tied to schema version?
7. Which business outcome does the fallback preserve?
8. Can the user see degraded mode?
9. Which negative fixture proves failure handling?
10. What browser/OS change forces recheck?

Guided and independent practice

Run the offline lab:

python -B lab/COM-036-LAB1/learner/run_checks.py

Inspect the baseline, then mutate it: deny push permission; make cache version stale; put the service worker in ACTIVATING; remove the camera device; disable secure context; and transfer to a second platform whose install behavior and push state differ.

Transfer rule: the previous verdict is never the oracle. Rebuild the matrix from evidence for the new platform.

Verification evidence

The evaluator must catch at least:

• READY with UNKNOWN/STALE/DISPUTED evidence;
• offline READY with incompatible cache version;
• push READY without permission or active subscription;
• camera READY without permission or device;
• a required unsupported capability with no fallback but a positive verdict;
• install readiness inferred only from manifest presence;
• transfer that copies the baseline verdict.

The oracle is the fixture plus deterministic rules—not a live browser, production push system, or hidden model reasoning.

Assessment and transfer

The summative task requires four moves: explain the COM-036 boundary; complete the baseline matrix; diagnose a stale-cache or denied-permission mutation; then recompute the same workflow on a second browser/OS combination.

A strong answer names the decisive field, missing/stale evidence, how the fallback preserves the business outcome, and what triggers the next recheck—not just the final state.

References and freshness

• W3C-APPMANIFEST — Web Application Manifest; rechecked 2026-09-14.
• W3C-SERVICE-WORKERS — Service Workers; rechecked 2026-09-14.
• W3C-PUSH — Push API; rechecked 2026-09-14.
• W3C-MEDIA-CAPTURE — Media Capture and Streams; rechecked 2026-09-14.
• WEBKIT-SAFARI26-WEBAPPS — Safari/iOS 26 Home Screen web-app behavior; vendor-specific implementation evidence only.
• LOCAL_DESIGN_AUTHORITY — frozen COM-036 Bible for fields and states.

This lesson deliberately avoids treating a static support table as universal truth. Platform behavior can change; recheck platform-sensitive claims by 2026-12-31 or earlier after a material browser/OS change.