source: .forge/discovery/research/pwa-basics.md · generated — edit the markdown, not this file

What a PWA Is, and How One Works

Orientation note, 2026-08-21. Written to ground the capture-app work: the PWA shell delivered in Foundation slice 1 (specs/foundation/001-app-shell-spec.md FR-C2) and the F36 capture stream that follows. Point-in-time — platform behaviour, iOS especially, moves faster than any document. Treat the mechanisms as durable and re-verify a per-platform specific before building on it. design/architecture.md § Trade-Show Capture App wins on anything it covers.

ℹ The whole thing in six sentences

A Progressive Web App is an ordinary website that has been given three extra things — a secure address, a small description file, and a background script — which together let a phone put an icon for it on the home screen and open it full-screen with no address bar, so it is indistinguishable from an installed app.

The background script, called a service worker, sits between the app and the internet and can answer requests from a copy stored on the device, which is where offline capability comes from. Nothing is downloaded from an app store; the icon points at a URL, and pushing a new version is a deploy, not a store submission.

Whether it works offline is entirely down to what you build: the platform gives you the tools, not the behaviour. Mobile responsiveness is a separate concern that PWAs neither provide nor require — it is plain CSS — although installing the app removes the browser’s own controls, which shifts a few layout responsibilities onto you.

One caveat before you start

Browser support for the platform-specific details below — particularly on iOS — moves faster than any document. Everything here reflects how browsers behaved through 2026. Treat the mechanisms as durable and the per-platform specifics as worth a quick re-check before you rely on one.

Part 1 — The basics

What the thing actually is, and how it sits next to the two alternatives you already know.

01 · What a PWA is

PWA stands for Progressive Web App. It is not a technology you install, a framework you adopt, or a file format. It is a label for a website that has crossed a threshold of capability.

Definition

A PWA is a website that a phone will let you install — giving it a home-screen icon and a full-screen window with no browser controls — and that keeps a copy of itself on the device, so it can open and do useful work when the network is bad or absent.

The important word in that definition is website. Everything is still HTML, CSS and JavaScript served over the web. There is no app bundle, no compiled binary, no store listing. A PWA and the site it came from are the same thing at the same address; the PWA is what that site becomes when a user chooses to install it.

In plain terms: it is a website wearing an app costume. The costume is convincing enough that most users never notice, and useful enough that the app keeps working in a hall with no signal.

The two things people mean when they say it

“It is installable”

The user gets an icon, a full-screen window, and something that appears in the app switcher alongside real apps. This is what the client notices.

— the visible half

“It works offline”

The app opens and functions with no connection, because a copy of it lives on the device and the code was written to cope with failed requests.

— the half you have to build

These two are technically independent. You can have an installable app that is useless offline, and an offline-capable site nobody ever installs. Most real PWAs want both, and the same background script tends to deliver both, which is why the two ideas get bundled under one name.

02 · Three ways to put an app on a phone

There are exactly three, and it helps to see the PWA as the middle one rather than as a novelty.

Plain website PWA Native app
How the user gets it Types a URL or follows a link Visits the URL, then chooses Install Downloads from the App Store or Play Store
What is on the device A browser cache that can vanish An icon, plus a managed copy of the app files A real installed application package
Opens without signal No Yes, if built for it Yes
Pushing an update Deploy; users get it on next load Deploy; users get it on next launch Store submission, review, then the user updates
Store review None None, unless you choose to list it Every release
How many builds One One One per platform (iOS, Android)
Hardware access Camera, location, files, sensors Same, plus background behaviour Everything the OS exposes
Discoverable by search Yes — it is a web page Yes — it is still a web page Only inside the store

The row that decides most projects is how many builds. A native app for both platforms is two codebases, two toolchains, two release processes and two review queues. A PWA is one of each, and the same code already serves the desktop browser.

WHAT "INSTALLING" ACTUALLY DOES Home screen ET Capture Mail Camera Maps tap Browser engine no address bar, no tabs, no browser buttons — just your app, full screen loads https://your-app-url the same site anyone could open in a normal browser tab Nothing was downloaded from a store. The icon is a pointer to a URL — with a stored copy of the files behind it.
Installing a PWA creates an icon and a chrome-free window. The app itself is still a website at a URL.

03 · What makes a site a PWA

Three ingredients. A browser checks for all three before it will offer to install anything.

1 · Served over HTTPS

The address must start with https://. No exceptions, other than localhost while you are developing.

2 · A web app manifest

A small .json file naming the app, its icons, its start address and how it should open.

3 · A service worker

A JavaScript file the browser keeps and runs in the background, which can answer network requests itself.

That is the entire entry fee. There is no certification, no registry, no vendor. If your site has those three things and the manifest points at icons of the right sizes, phones will offer to install it.

⚠ The common misunderstanding

Having the three ingredients makes an app installable. It does not make it good offline, or fast, or usable on a small screen. Those are things you build. A great many sites technically qualify as PWAs and behave like broken websites the moment the signal drops.

04 · What “progressive” means

The word is a design principle, not a feature, and it is the reason the approach is safe to adopt.

Progressive enhancement: the app works for everyone at a basic level, and gets better on devices and browsers that support more. Nobody is locked out because their phone is old or their browser is unusual.

Concretely, one URL produces four different experiences without any branching in your deployment:

  1. An old browser with no service-worker support gets a normal website. Everything works; nothing is cached.
  2. A modern browser gets the same site, plus a cached copy, so a repeat visit is fast and survives a dropout.
  3. A user who taps Install gets a home-screen icon and a full-screen window.
  4. A platform that supports notifications and background sync gets those too, and one that does not simply does without.

This is the practical difference from native development, where an unsupported OS version means a user gets nothing. Here the floor is “an ordinary web page”, which is usually fine.

Part 2 — How it actually works

One mechanism does nearly all the work. Understand the service worker and the rest follows.

05 · The service worker

This is the engine of the whole idea, and it is simpler than its reputation.

Definition

A service worker is a JavaScript file the browser downloads once and then keeps. It runs separately from any page, and the browser routes every network request the app makes through it first. The worker can answer from a local copy, go to the network, or do something in between.

Think of it as a receptionist you hire, who sits between your app and the internet. Every time the app asks for something — a page, a stylesheet, an image, some data — the receptionist intercepts the request and decides what to do with it. Do I have this in the filing cabinet already? Should I go and fetch it? Should I hand over the old copy because the phone lines are down?

EVERY REQUEST GOES THROUGH THE WORKER The page your app's screens asks Service worker runs in the background, outlives the page, sees every request app files data, uploads Cache on the device HTML, JavaScript, CSS, fonts, icons The network your server, never answered from cache The split is a rule you write: app files may be cached, live data may not.
The service worker is a programmable middleman. What it caches and what it passes straight through is a decision you make in code.

Three properties that surprise people

  • It outlives the page — Close every tab and the worker can still be woken by the browser — to receive a push notification, or to retry a queued upload.
  • It cannot touch the screen — No access to the page’s HTML. It handles requests and storage; the page handles the interface. They talk by messages.
  • It is sticky — Once installed it stays until it is replaced or the user clears site data. This is its greatest strength and its most dangerous property — see section 09.

06 · What happens on each visit

Three scenarios cover almost everything.

THREE VISITS FIRST VISIT App loads from network Worker installs Files copied to the cache NEXT VISIT Worker takes the request Tries the network Fresh copy, cache refreshed NO SIGNAL Worker takes the request Network fails Serves the stored copy The app opens in all three cases. Only the third one is doing anything clever.
The first visit is what pays for the third. Nothing can be served offline that was not fetched at least once while online.

⚠ The consequence people miss

A PWA cannot work offline on its first ever launch. Someone has to open it once with a connection so the worker can install and fill the cache. For a trade show, that means installing and opening the app before you are standing in the hall.

The three caching strategies, in plain terms

Strategy What it does Right for
Cache first Answers from the stored copy immediately; only goes to the network if it has nothing. Things that never change — a logo, a versioned script file.
Network first Tries the network; falls back to the stored copy if the request fails. The app itself, when you would rather be slightly slower than slightly stale.
Stale while revalidate Serves the stored copy instantly, then quietly fetches a fresh one for next time. Content that can be a few minutes old — a list, a feed.

Picking one per kind of file is most of the design work in a service worker. Getting it wrong is how apps end up serving last week’s build to a user who cannot make it stop.

07 · The cache, and what must never go in it

The service worker’s cache is not the browser’s ordinary cache. It is a separate store your code writes to explicitly, and it is not cleared by a normal refresh, a hard refresh, or restarting the phone.

⚠ The single most expensive mistake

Caching an API response. If the worker stores the answer to /api/customers, that answer survives your redeploy, survives the user’s hard refresh, and survives them closing the app. The user sees stale data and every remedy they know does nothing. Support cannot fix it over the phone.

App files are safe to cache because their filenames contain a content hash — a new build produces new filenames, so old entries are simply never asked for again. Live data has no such property.

Allow-list, not deny-list

There are two ways to write the rule, and only one of them is safe:

Deny-list fails open

“Cache everything, except paths starting with /api/.” The day somebody adds an endpoint on a different path, it silently starts being cached. Nothing warns you.

Allow-list fails closed

“Cache only these file types and the app document itself. Everything else goes straight to the network.” A new path is simply not cached until someone deliberately adds it.

This is the rule the Empire Teas capture app uses, and section 32 shows the actual code.

08 · The manifest

The manifest is a small JSON file — typically under fifty lines — that answers the phone’s questions about how to present your app. It is the least clever and most visible part of a PWA: get it wrong and the icon looks broken on the home screen.

Field What it controls Notes
name The full app name, shown during installation. Can be long.
short_name The label under the home-screen icon. About 12 characters before it is truncated.
icons The artwork. At minimum 192px and 512px squares. Add a maskable one or Android will crop your logo into its circle badly.
start_url Which screen opens when the icon is tapped. Not necessarily the same as your home page.
scope Which URLs count as “inside the app”. Navigate outside it and the browser reappears around your app.
display How much browser interface to keep. standalone is the usual choice — see section 26.
theme_color Tints the status bar and the window edges. The cheapest way to look deliberate.
orientation Locks to portrait or landscape, or allows both. Only honoured when installed.
background_color The colour of the splash screen while the app boots. Match your app’s background or you get a flash.

In plain terms: the manifest is the app’s ID card. The service worker makes it capable; the manifest makes it look and behave like something that belongs on a home screen.

09 · Why users see an old version

This is the number-one PWA support ticket, and it is worth understanding precisely, because the intuitive fix does not work.

When you deploy, the browser eventually notices that sw.js has changed and downloads the new one. But the new worker does not take over immediately. The old one is still running the currently-open app, and the browser will not swap engines mid-flight. The new worker installs and then waits.

THE UPDATE LIFECYCLE You deploy a new build Browser sees a changed sw.js New worker installs, then waits Activates on the next launch — new version live a refresh does not always end the wait
The waiting step is deliberate — but it is why "I refreshed and it is still the old one" is a real report and not user error.

You have three options, and the choice is a product decision:

  • Wait it out. The new version takes over next time the app is fully closed and reopened. Safest, slowest.
  • Skip the wait. The new worker takes over as soon as it installs. Fast, but a running app can find its files swapped underneath it.
  • Tell the user. Show a small “A new version is ready — Reload” bar. Best of both, and the only option that is honest with someone mid-task.

Two habits that prevent most of the pain

Put the build version in the cache name, so each deploy uses a fresh cache and the old one is deleted rather than reused. And never cache API responses (section 07), so the worst a stale worker can serve is an old interface against current data — annoying, not wrong.

10 · HTTPS, and why it is non-negotiable

Service workers only run on secure origins. This is not pedantry: a worker can rewrite every response the app receives, forever. Over an unencrypted connection, anyone on the same café Wi-Fi could install one on your users’ devices and it would persist long after they left the café.

Practically this costs nothing. Certificates are free and automatic on every mainstream host, and localhost is exempt so local development is unaffected. It does mean:

  • You cannot demo a PWA properly from a bare IP address or a plain http:// staging box.
  • Opening the built files directly from disk will not exercise the service worker — you need a real server.
  • Mixed content breaks it: one image loaded over http:// can invalidate the secure context.

Part 3 — Offline

The headline claim, examined honestly: what you get free, what you have to build, and what stays impossible.

11 · Does it work offline?

Yes — but “offline” is doing a lot of work in that sentence. The honest answer is in two parts.

What you get almost free a day’s work

The app opens with no connection. The screens render, navigation works, anything already downloaded is there. No spinner, no dinosaur, no error page.

This is the service worker caching the app’s own files. It is close to automatic once the worker exists.

What you have to build real work

The app does something useful with no connection — showing data fetched earlier, and accepting new input that is sent later.

This is application code: local storage, a queue, retry logic, conflict handling, and an interface that tells the user what has and has not been sent.

⚠ Where projects go wrong

“It is a PWA, so it works offline” is a scoping error that has cost many teams a sprint. The platform gives you the ability to work offline. Every offline behaviour a user notices is something a developer designed, built and tested. Budget for it explicitly.

12 · The three levels of offline

Being precise about which level you are buying prevents most disappointment.

Level Name What the user can do with no signal Cost
1 Shell offline Open the app. See the interface. Navigate between screens. Any data area shows an honest “no connection” state. Low — the service worker does it.
2 Read offline All of the above, plus see data that was downloaded earlier — their customer list, today’s schedule, a price sheet. Medium — needs a local database and a sync strategy.
3 Write offline All of the above, plus create and edit things that are saved locally and sent when the connection returns. High — needs a queue, retries, duplicate protection and conflict rules.

Level 3 is where trade-show capture lives, and it is worth being clear about why it is the expensive one: the moment a device can create data while disconnected, you have a distributed system. Two people can edit the same record from different queues. A submission can be sent, arrive, and have its acknowledgement lost — so the phone retries and the server sees it twice. These are not edge cases at a busy exhibition; they are Tuesday.

The rule that makes level 3 tractable

Every queued item carries a unique key generated on the device, and the server treats a repeat of a key it has already seen as a no-op rather than a new record. This makes “send it again” always safe, which turns a distributed-systems problem into a retry loop. It is the same principle this project applies to background jobs generally.

13 · The offline queue

This is the pattern behind every credible offline-capable app. It is worth seeing once in full.

CAPTURE NOW, SEND LATER Rep taps Save card photo + notes Written to the phone local database confirmed to the user immediately Try to send unique key attached online no signal Server accepts removed from queue Stays queued "3 waiting to send" when the connection returns, flush the queue
The user is confirmed by the local write, not by the server. That single decision is what makes the app feel instant in a hall with no signal.

What triggers the retry

Three mechanisms, in decreasing order of reliability, and a robust app uses all three because none is universal:

  1. The app is open and notices the connection came back. The browser fires an event; you flush the queue. Works everywhere. Only works while the app is open.
  2. The app is opened again later. On startup, check the queue and send anything pending. Works everywhere. Requires the user to come back.
  3. Background sync. The browser wakes the service worker when connectivity returns, even with the app closed, and lets it send. Genuinely magic — and only available on Chromium-based browsers, which means not on iPhone.

⚠ Design for the absence of background sync

Because iOS does not have it, never let a queued item’s delivery depend on it. Build for options 1 and 2, treat option 3 as a bonus on Android, and always show the user how many items are waiting so they can open the app on the coach home and watch the queue drain.

14 · What still breaks offline

Some things cannot be made to work without a connection, no matter how the app is built. Knowing which is which prevents promising the impossible.

Capability Offline? Why
Opening the app, navigating, forms works All from the cached copy on the device.
Taking a photo, scanning a QR code works The camera is local hardware. Reading a QR code is arithmetic done on the device.
Viewing data fetched earlier works If — and only if — you deliberately stored it locally.
Saving new records works Written locally and queued. Level 3 above.
Logging in for the first time no Credentials are checked by the server. An existing session can be kept valid locally; a fresh sign-in cannot.
Reading a business card with AI no The model runs in the cloud. Capture the photo offline, read it when the connection returns.
Anything requiring live data no Current prices, another user’s changes, a search across the full database.
Sending email or notifications no Server-side by definition. Queue the intent, send on reconnect.

The design rule that follows

Split every feature into “what can happen on the device” and “what needs the server”, then make the device half complete on its own. Photographing a card is device-side and must never block on a network call; reading the card with AI is server-side and belongs in the queue. The user should never be prevented from capturing because something later in the pipeline is unavailable.

15 · Where offline data lives

Four storage places, with different rules. Choosing wrongly is a common source of data loss.

Store Capacity Use it for
Cache Storage Large The app’s own files — HTML, JavaScript, CSS, fonts, icons. Managed by the service worker.
IndexedDB Large Structured data and the outbound queue. Photos too, stored as binary. This is where real offline data belongs.
localStorage About 5 MB Small preferences only. It is synchronous, so writing to it freezes the interface — never put a queue here.
Cookies About 4 KB Session identity. Sent with every request, so nothing else belongs in them.

Two things about the quota

It is generous but not guaranteed. Modern browsers will hand a site hundreds of megabytes to several gigabytes, plenty for a day of card photographs. But the storage is evictable: under real disk pressure the operating system can clear it, and browsers have their own housekeeping that removes data for sites the user has not opened in a while. Installing the app and using it regularly makes eviction much less likely, and a browser can be asked to mark the storage as persistent — but the honest posture is that a phone is a cache, not a filing cabinet.

Therefore: get data off the device. The queue should drain at the first opportunity and the app should say plainly how many items are still local. “47 leads captured, all sent” is a very different end-of-day state from “47 leads captured” — and only one of them survives a lost phone.

Part 4 — Installing and using it on a phone

The practical half. Nothing here needs a developer — this part can be handed to a sales rep.

THREE INSTALL PATHS ANDROID Open the link in Chrome Menu, then "Install app" Icon in the app drawer IPHONE / IPAD Open the link in Safari Share, "Add to Home Screen" Icon on the home screen COMPUTER Open in Chrome or Edge Install icon in the address bar Its own window the browser may also offer a banner
Every path starts with opening a normal link. There is no store, no download, and no account needed.

16 · Installing on Android

The best-supported path, and the one that produces the most convincing result.

  1. Open the app’s link in Chrome (or Edge, Samsung Internet, Brave — anything Chromium-based).
  2. Wait for it to finish loading. The browser needs to see the manifest and the service worker before it will offer anything.
  3. Either tap the Install banner if one appears, or open the ⋮ menu and choose Install app / Add to Home screen.
  4. Confirm the name. The icon appears on the home screen and in the app drawer.

✔ What Android does that is worth knowing

Chrome quietly generates a real Android package for the installed site. The result is that it behaves like a properly installed app: it appears in the app drawer, gets its own entry in the recent-apps switcher, can be set as a default handler for its own links, and shows up in Settings under installed apps with its own storage entry. Users genuinely cannot tell.

A developer can also add a button inside the app that triggers the install prompt directly — the browser hands the page the opportunity, and you choose when to use it. That is nicer than telling users to hunt through a menu, and it means you can put the prompt after the user has done something successful rather than in their face on arrival.

17 · Installing on iPhone and iPad

It works, and it works well — but the path is more hidden and there are real caveats. Read this section before promising an iPhone user anything.

  1. Open the link in Safari.
  2. Tap the Share button — the square with an arrow coming out of it, at the bottom of the screen.
  3. Scroll the list and tap Add to Home Screen.
  4. Edit the name if you like, then tap Add.

⚠ The iOS caveats, in order of how often they bite

  • No automatic prompt. iOS never offers to install anything. If nobody tells the user those four steps, it never happens. This is a rollout problem, not a technical one — see section 22.
  • Historically Safari-only. The reliable path is Safari’s own share sheet. Support in other iOS browsers has moved recently enough that it is worth testing on the actual devices your users carry rather than assuming.
  • Notifications need the install. On iOS, web push works only for apps added to the home screen — a website in a Safari tab cannot notify. So the install is not cosmetic if you want notifications.
  • No background sync. Queued items are sent when the app is open, not while it sits closed in a pocket.
  • Storage is more fragile. Safari is aggressive about clearing data for sites that go unused. Installed home-screen apps get better treatment than tabs, but do not treat an iPhone as durable storage for un-sent work.

None of this makes the approach unviable on iPhone — the Empire Teas capture app is expected to run on both platforms. It does mean the iPhone path deserves its own line in the rollout instructions and its own pass in testing.

18 · Installing on a computer

Often forgotten, and genuinely useful — the same app in its own window, in the dock or taskbar, with no tabs around it.

  • Chrome / Edge — An install icon appears at the right-hand end of the address bar. Or use the menu, then “Install this site as an app” / “Apps”.
  • Safari on macOS — File, then “Add to Dock”.
  • Firefox — Does not install web apps on the desktop. The site still works normally in a tab.

For an internal tool this is a cheap win: back-office staff get something that looks like an application and lives beside their other apps, from the same deploy that serves the phones.

19 · What it feels like once installed

Concretely, from the user’s side:

✅ An icon on the home screen, with your artwork and your name under it. ✅ A splash screen while it starts, in your colours, instead of a white flash. ✅ No address bar, no tabs, no browser buttons. The status bar takes your theme colour. ✅ Its own tile in the app switcher, so switching to it is muscle memory rather than hunting for a tab. ✅ It opens when there is no signal — the point of all of this. ✅ It can be uninstalled like any app, by long-pressing the icon.

And what is different from a native app, if you look for it:

⛔ No entry in the App Store or Play Store, so no store rating, no store search, no “get it on” badge. ⛔ The first launch after installing may still need a moment to warm up. ⛔ On iOS, no back button — the app must provide its own; see section 26. ⛔ Some deep OS integrations are unavailable — no home-screen widgets, no Siri shortcuts, no share-sheet targets on iOS.

20 · Updating, uninstalling, resetting

Action What the user does What actually happens
Update Nothing. There is no update button and no store notification. The app checks for a new version when it launches and takes it on the next launch after that. Section 09 explains the delay.
Force an update Fully close the app — swipe it out of the app switcher — and reopen it. Twice if needed. Ends the waiting worker’s wait. This is the correct answer to “it still looks old”, and it is worth putting in the user instructions.
Uninstall Long-press the icon, choose Remove or Uninstall. The icon goes. On Android the stored data usually goes too; on iOS removing the icon clears the app’s data. Anything still queued is lost.
Start clean Uninstall, then clear the site’s data in browser settings, then reinstall. The nuclear option for a wedged service worker. Rarely needed, but it is the one thing that always works.

⚠ Warn users before an uninstall

If an offline queue exists, uninstalling with items pending destroys them silently. An app that can hold un-sent work should say so on screen — a persistent “3 leads waiting to send” marker — so nobody removes the app on the train home while a day’s captures are still in it.

21 · Notifications and permissions

A PWA can ask for the same permissions a native app can, through the same operating-system prompts. The list that matters:

Permission Support Notes
Camera and microphone Everywhere Requires HTTPS. Full live camera access, not just a file picker.
Location Everywhere Same prompt and same accuracy as a native app.
Files and photos Everywhere Pick existing files, or open the camera directly from a file input.
Push notifications Android, desktop, and iOS only when installed Ask at a moment that makes sense, not on arrival — a refusal is hard to reverse.
Background sync Chromium only Never depend on it; see section 13.
Bluetooth, NFC, USB Chromium only, not on iOS If your app must talk to a badge scanner over Bluetooth, this is where a PWA stops being enough.
Contacts, SMS, telephony Effectively unavailable You can open a dialler or a message with a link, but not read the address book.

Ask late, and explain first

Every permission prompt is a one-shot: a user who taps “Don’t allow” is expensive to recover, because the second chance lives in the operating system’s settings rather than in your app. Explain in your own interface why you need it, and only then trigger the real prompt — ideally at the moment the user is trying to do the thing that needs it.

22 · Getting it onto a team’s phones

The installation itself is thirty seconds. Getting a whole sales team installed before a show is the part that actually needs planning, because there is no store to do the work for you.

  1. Send a link that survives forwarding. A short, memorable URL. It will end up copied into WhatsApp, read out loud, and typed by hand.
  2. Send platform-specific instructions. Two short sets — Android and iPhone — with the exact menu wording and a screenshot each. One generic set will fail the iPhone users.
  3. Put an in-app prompt on the page. A visible “Add this to your home screen” hint for iOS visitors is the single highest-value thing you can add, because iOS will never prompt on its own.
  4. Do it a week early, not on the morning. Installing needs a connection, the first launch needs a connection, and signing in needs a connection. Exhibition-hall Wi-Fi is where all three go to die.
  5. Have every rep open it once and capture a test lead. This proves the install, warms the cache, establishes the login session, and surfaces the one phone that is going to be a problem — while there is still time to deal with it.

✔ The one-line rollout rule

Install and open the app while you still have good signal. Everything a PWA does offline depends on something it downloaded while online.

Part 5 — Mobile responsiveness

How a layout adapts to a screen — a separate subject that meets the PWA at exactly three points.

23 · Responsive is not the same as PWA

These two get conflated constantly, so it is worth being blunt about it.

Responsive design

The layout adapts to the size of the screen — one column on a phone, several on a desktop. Pure CSS. Has existed since 2010 and has nothing to do with installability or offline.

Progressive Web App

The site can be installed and can work without a connection. Manifest plus service worker. Says nothing whatsoever about how the layout behaves at any width.

You can build a perfectly installable, fully offline-capable PWA that is unusable on a phone because the layout was never made responsive. You can build a beautifully responsive site that is not a PWA at all. They are independent choices that happen to be made together, because the same person usually wants both.

The relationship in one sentence: being a PWA is what makes the app installable and offline-capable; being responsive is what makes it usable once it is open. Installing a bad mobile layout just gives you a bad mobile layout with an icon.

Where they genuinely interact is narrow but important, and it is covered in section 26: installing the app removes the browser’s own interface, which hands you responsibilities the browser used to carry.

24 · How responsive layout works

Four mechanisms, in the order they matter.

1 · The viewport tag

One line in the HTML, and without it nothing else works:

<meta name="viewport" content="width=device-width,initial-scale=1">

Without it, a phone assumes the page was designed for a desktop, renders it at about 980 pixels wide and shrinks the whole thing to fit — the familiar zoomed-out page with unreadable text. The tag tells the phone to use its real width instead. It is the single most consequential line in mobile web development, and it is one line.

2 · Fluid sizes instead of fixed ones

A box that is 380px wide overflows a 360-pixel phone. A box that is 100% wide, or that sits in a grid told to fit “as many 260-pixel columns as will fit”, adapts on its own. Most responsiveness is simply the absence of hard-coded widths — the layout works at every size because nothing ever asserted a size.

3 · Breakpoints

Where fluidity is not enough, CSS can apply different rules above or below a given width. This is what turns a three-column desktop layout into a single stack on a phone. The professional habit is to write the phone layout as the default and add complexity as the screen grows — it produces simpler CSS and a mobile experience that was designed rather than salvaged.

ONE DOCUMENT, THREE ARRANGEMENTS phone · 1 column tablet · 2 columns desktop · sidebar + 2 columns same HTML · same components · CSS decides the arrangement at each width
Nothing is duplicated and there is no separate mobile site. One set of components; the stylesheet chooses how they sit.

4 · Content that adapts too

Layout is the easy half. The harder half is deciding what a small screen should show at all — a table with eleven columns does not become usable by being narrower. On a phone it becomes a list of cards showing the three fields that matter, with the rest a tap away. That is a product decision made per screen, and it is where most of the real effort in “making it mobile” actually goes.

25 · Designing for fingers

A phone is not a small desktop; it is a different input device held in one hand, often outdoors, often by someone standing up. The practical rules:

  • Touch targets around 44 pixels square. Roughly a fingertip. Anything smaller is a mis-tap waiting to happen, and mis-taps in a capture app mean lost leads.
  • Space between targets. Two correctly-sized buttons touching each other are still one target as far as a thumb is concerned.
  • Important controls at the bottom. The top of a modern phone is out of reach of a thumb. Primary actions belong in the lower third.
  • Body text at 16 pixels or more. Below that, iOS zooms the page automatically when a field is focused, which yanks the layout sideways.
  • The right keyboard. Marking a field as numeric or as an email address changes which keyboard appears. Free, and it makes a form feel considered.
  • No hover-only anything. There is no hover on a touchscreen. A tooltip that only appears on hover does not exist on a phone.
  • Real-world contrast. An exhibition hall is bright and the phone is at arm’s length. Elegant low-contrast greys are unreadable there.

26 · What standalone mode changes

Here is where the PWA and responsiveness genuinely meet. Setting display: standalone removes the browser’s interface — and the browser was quietly providing four things you now own.

IN A TAB versus INSTALLED status bar address bar · reload · share your app back · forward · tabs browser tab status bar, tinted by theme_color your app edge to edge home indicator — keep this area clear installed · standalone install +68px of screen, −back button
Installing gives you the browser's screen space and takes away its controls. Both halves of that trade need a design answer.

The four things you take over

  1. Navigation. There is no browser back button. Android still has its system back gesture; iOS gives you only an edge swipe that users will not discover. Every screen below the top level needs a visible way back — which is exactly why this project’s plan rules require sub-views to declare a back-navigation affordance.
  2. The notch and the home indicator. Your app now extends under them. The operating system exposes the size of each unsafe edge as a CSS value, and your padding should use it; otherwise a header sits under the camera cutout and a bottom button sits under the home bar.
  3. The status bar’s colour. The manifest’s theme_color tints it. Left unset, you get a mismatched strip along the top that makes the whole app look unfinished.
  4. Refresh. There is no reload button. If a screen can get stuck, it needs its own retry — and if you want pull-to-refresh, you build it.

Two more that catch people out

The old 100vh trick for “full screen height” is wrong on mobile, because the browser’s own bars appear and disappear as you scroll; the newer dynamic viewport units exist to fix exactly this. And the manifest’s orientation lock only applies when installed — so a portrait-locked app is still rotatable in a browser tab, and both need to be tested.

27 · Testing it properly

Responsiveness and PWA behaviour both fail in ways that a desktop browser will happily hide from you.

Check How
Layout at every width Browser developer tools have a device-simulation mode. Drag the width continuously rather than jumping between presets — breakage lives between the presets.
The install actually works Run an in-browser app audit; it reports whether the app is installable and names what is missing.
Offline behaviour The developer tools have an offline switch. Flip it and use the app — do not just reload once.
The slow, flaky case Simulated slow connections. This is closer to an exhibition hall than a clean offline switch, and it breaks more apps.
What the worker cached The Application panel lists every cache and its contents. Confirm with your own eyes that no API response is in there.
Standalone mode Only on a real device, actually installed. Simulators do not reproduce the notch, the home indicator, or the missing back button.
The update path Deploy twice and watch a real installed instance take the change. This is the step everyone skips and the one that generates support tickets.

⚠ One real device, minimum

Test on an actual iPhone and an actual mid-range Android. Simulated views tell you nothing about touch accuracy, outdoor readability, real network flakiness, or the iOS install path — and those are precisely the things that decide whether a rep uses the app or goes back to a stack of business cards.

Part 6 — The trade-offs

Both columns, honestly, and a way to decide.

28 · The pros, honestly

✅ One codebase, every device. iPhone, Android, tablet, laptop — one build, one test cycle, one deploy. Against native, this is roughly a halving of the work before anything else is counted. ✅ No app store. No developer accounts, no annual fees, no review queue, no rejection because a reviewer disliked a screen. A fix reaches every user in minutes. ✅ Everyone is on the current version. No fleet of users stuck on a build from March because they never tapped Update. Old versions genuinely do not persist. ✅ Installing costs the user almost nothing. A few megabytes and two taps, versus a hundred-megabyte download over conference Wi-Fi. ✅ A link is the whole distribution mechanism. Send a URL. That is the rollout. It works in an email, a message, a QR code on a badge. ✅ It is still a web page. Shareable, linkable, bookmarkable, openable by someone who has not installed anything. ✅ Ordinary web skills. The team that builds the main application builds this too, with the same tools, review process and CI. ✅ Offline and installed when it matters. The two things people historically switched to native for are both available.

29 · The cons, honestly

⛔ iOS is the weak platform. No install prompt, notifications only when installed, no background sync, more aggressive storage clearing. Everything works — but the iPhone path needs its own testing and its own instructions. ⛔ No store presence. If discovery through the App Store matters commercially, a PWA does not give you it. For an internal tool this is a non-issue; for a consumer product it can be decisive. ⛔ Some hardware is out of reach. Bluetooth and NFC are Chromium-only and absent on iOS; contacts, SMS and deep OS integration are unavailable everywhere. A dedicated scanner over Bluetooth is a genuine reason to reconsider. ⛔ Offline is work you have to do. It is not a checkbox. Levels 2 and 3 in section 12 are real engineering, and the estimate has to include them. ⛔ Service workers are a sharp tool. A caching mistake is unusually hard for a user to recover from, because the ordinary remedies do not clear it. ⛔ The install has to be taught. Users know how app stores work. Nobody instinctively knows to find “Add to Home Screen” in a share sheet. ⛔ Heavy graphics and heavy computation. Fine for forms, lists, cameras and photographs. Not the right choice for a 3D game or intensive on-device processing. ⛔ It can feel slightly less native. Scroll physics, transitions and keyboard behaviour are close now, but a discerning user on a high-end phone can sometimes tell.

30 · When to choose one

A PWA is the right call when…

  • It is an internal or B2B tool for a known group of people.
  • The same product also needs to work on a desktop.
  • The team already builds web applications.
  • Updates need to be frequent and immediate.
  • Store discovery is irrelevant.
  • Device needs stop at camera, location and files.

Reach for native when…

  • Store presence is part of the business model.
  • You need Bluetooth or NFC hardware on iPhones.
  • The app must do heavy work in the background while closed.
  • Widgets, watch apps or deep OS integration are required.
  • Performance demands are at the level of games or video editing.

✔ The pragmatic sequence

Build the PWA first. It is one codebase, it ships in a fraction of the time, and it answers the question empirically: use it for one real event and see what is genuinely missing. If a hard native requirement emerges, an Android PWA can be wrapped and listed in the Play Store with modest effort, and only then does a native iOS build need to be justified on evidence rather than assumption.

Part 7 — All of it, applied to Empire Teas

Everything above, mapped onto the trade-show capture app — using what is actually in the repository rather than a generic example.

31 · Why the capture app is a PWA

The capture app exists to be used by a sales rep standing at an exhibition stand, holding a stack of business cards, on hall Wi-Fi. Every property of that situation points at the same answer.

The situation Why a PWA answers it
Exhibition Wi-Fi is unreliable and often absent The app opens from its cached copy and captures into a local queue. A dead network slows the pipeline; it does not stop the rep.
Reps carry their own phones — a mix of iPhone and Android One build serves both. No pair of native codebases, no pair of release processes.
Rollout happens days before a show Send a link. No store submission, no review window, no fleet of stale installs.
The app needs the camera and a QR scanner Both are ordinary web capabilities on a secure origin, on every platform in scope.
It must feed the CRM, not replace it It is a thin capture surface over one API slice on the same backend. A native app would be a large amount of machinery for a small amount of product.
Notifications go out by email Lead notifications are sent server-side, so the weakest cross-platform web capability is not on the critical path at all.
THE CAPTURE APP, END TO END ET Capture installed PWA cached shell opens offline local queue of captures app files · cached /api/ · never cached CloudFront + S3 the static bundle AWS ACCOUNT · US-EAST-1 Backend API the capture slice Bedrock reads the card Database the lead record SES notification email CRM lead intake
Two request paths from one app. The green one may be served from the device; the blue one never is — which is the whole cache-policy decision in a picture.

32 · What we have built so far

The PWA shell landed with the first foundation slice — deliberately ahead of the capture features, so that the installable path is proven before anything depends on it. As of that slice the repository contains four things worth knowing about.

The manifest

  • Name — “Empire Teas — Trade-Show Capture”, shortened to “ET Capture” under the icon.
  • Display — standalone — installed, it takes the whole screen with no browser controls.
  • Orientation — portrait — a one-handed capture app has no use for landscape.
  • Icons — 192px and 512px, plus a maskable 512px so Android’s icon shapes do not crop the logo badly.
  • Theme colour — A tea green, which is what tints the status bar.

The service worker

Hand-written, about forty lines, and deliberately so: a generated pre-cache configuration is very difficult to read, and the acceptance criterion for this slice was that the request handling could be inspected against an API path. It does three things.

  1. Network first, cache as fallback. A request is tried against the network; the answer is stored and returned. If the network fails, the stored copy is served. Cache-first would serve a stale interface after a deploy — the exact failure this worker exists not to add.
  2. An allow-list, never a deny-list. The document itself and a fixed list of asset extensions may be cached. Same-origin only, GET only, and anything under /api/ is passed straight through untouched — the worker explicitly declines to handle it rather than handling it and choosing not to store it.
  3. A version-stamped cache name. The cache is named after the app version, substituted into the file at build time. A deploy therefore uses a new cache and deletes the old one on activation, instead of inheriting entries from a different build.

The part that is easy to miss

The caching rule exists twice — once as a tested pure function in the application source, and once inline in the worker, because a classic service worker cannot import from the bundle. Two copies of a rule drift. So the build runs a validation script that asserts they still agree, and the build fails if they do not. It also asserts that the version substitution actually happened, because that step failing silently would mean every deploy quietly reusing one cache.

Registration only in a real build

The worker is registered only in a production bundle, never during local development. A worker caching development-server assets and then serving them after a change produces the most confusing bug in web development — an edit that appears to have no effect. This is why pnpm dev deliberately has no service worker, and pnpm preview is where you go to exercise one.

Validation in the build and in CI

The manifest and the worker are checked on every build and again on every pull request, so a broken manifest or a failed version substitution stops at CI rather than at a trade show.

Command What it gives you
pnpm dev The app on port 5173. No service worker — by design.
pnpm build The production bundle, then the manifest and worker validation.
pnpm preview Port 4173, service worker active. This is where you test offline and installation.

33 · What comes with the capture features

The shell proves the installable path. The capture stream that follows is where the interesting offline work lives — and reading it against the earlier parts of this document shows exactly which sections become load-bearing.

Feature What it needs from this document Level
Camera and QR capture Permissions, section 21. Works offline — the camera is local hardware. device-side
Offline submission queue Sections 12 and 13 in full: local storage, unique keys, retry on reconnect, a visible count of what is waiting. level 3
Business-card reading Server-side and therefore queued. Capture the photograph offline; read it when the connection returns. deferred
Research and scoring Server-side. Nothing to do offline beyond showing an honest pending state. deferred
Lead notification email Sent by the backend, so the cross-platform notification gap never appears on the critical path. server-side
Feeding the CRM lead intake Ordinary API work once a capture has arrived. server-side

⚠ The three things worth deciding early

  1. How duplicates are prevented. A queued capture that is sent, arrives, and loses its acknowledgement will be retried. The unique-key-plus-ignore-repeats rule needs to exist on the server before the queue exists on the phone, not after.
  2. What the rep sees about un-sent work. A persistent, unmissable count. Everything about trusting the app offline rests on the user being able to see that nothing has been lost.
  3. How photographs are held and released. Card images are the largest thing the queue will carry, and storage on a phone is evictable. They should leave the device at the first opportunity, and the app should be explicit about which ones still have not.

Part 8 — Reference

Every term used above, defined in one line.

34 · Glossary

Term Meaning
PWA Progressive Web App — a website that can be installed to a home screen and can work without a connection.
Service worker A background script the browser keeps, which intercepts the app’s network requests and can answer them from a local copy.
Web app manifest A small JSON file describing the app’s name, icons, start address and how it should open once installed.
App shell The app’s own files — HTML, JavaScript, CSS, fonts, icons. The part that is safe to cache.
Cache Storage The store a service worker writes to. Separate from the ordinary browser cache and not cleared by a refresh.
IndexedDB A database inside the browser, on the device. Where offline records and the outbound queue belong.
Standalone mode The installed app’s display mode: full screen, no address bar, no browser buttons.
Scope The range of URLs that count as inside the app. Navigating outside it brings the browser interface back.
Background sync A browser feature that wakes the service worker to send queued data when connectivity returns, even with the app closed. Chromium only.
Offline queue Records saved on the device because they could not be sent, and re-sent later.
Idempotency key A unique identifier on each queued item, so a server that sees it twice records it once. What makes retrying safe.
Cache first Answer from the stored copy; only use the network if there is nothing stored.
Network first Try the network; fall back to the stored copy if it fails. The safer default for an app’s own files.
Stale while revalidate Serve the stored copy immediately, then fetch a fresh one for next time.
Viewport tag The line of HTML that tells a phone to render at its real width instead of pretending to be a desktop.
Breakpoint A screen width at which the stylesheet applies a different layout.
Responsive design A layout that adapts to the size of the screen. Independent of whether the app is a PWA.
Safe area The part of the screen not covered by a notch, a camera cutout or the home indicator.
Touch target The tappable area of a control. About 44 pixels square is the working minimum.
Secure origin An address served over HTTPS. Required for service workers, camera and location.
Install prompt The browser’s offer to add the app to the home screen. Automatic on Android, never automatic on iOS.
Progressive enhancement Building so the app works everywhere at a basic level and improves where the platform allows more.

✔ If you remember only six things

  1. A PWA is an ordinary website plus three ingredients — HTTPS, a manifest, a service worker — which together let a phone install it and open it full-screen.
  2. The service worker is the whole mechanism: it sits between the app and the network and can answer from a copy on the device.
  3. Offline is not free. Opening offline is nearly automatic; doing useful work offline is real engineering, and a queue that accepts new records is the expensive part.
  4. It cannot work offline on its first launch. Someone must install and open it with a connection first — which makes “install a week before the show” a rollout rule, not advice.
  5. Responsiveness is a separate subject. Being a PWA makes the app installable; being responsive makes it usable. Installing only removes the browser’s controls, and you inherit what they were doing — the back button most of all.
  6. iOS works, but on its own terms: no install prompt, no background sync, notifications only once installed, and storage you should not rely on. Plan for it explicitly rather than discovering it at the stand.

Generated from .forge/discovery/research/pwa-basics.md by .claude/lib/render-docs-html.js. Markdown is canonical.