Wiki · Concept · Last reviewed June 25, 2026

Launch Handler API

The Launch Handler API lets an installed web app declare how future launches are routed to new or existing app windows.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: browser API, progressive web apps, installed web apps, launch routing, agents, governance

Definition

The Launch Handler API is a web platform feature for installed progressive web apps. It extends the Web App Manifest with a launch_handler member and exposes window.launchQueue so a web app can receive launch parameters. MDN describes the feature as a way to control whether a PWA launch uses an existing window or creates a new one, and how the target launch URL is handled.

The API matters because an installed web app is not launched only once. A user may open it from an icon, click a captured link, receive a file handoff, or return through an operating-system surface. Launch handling turns those repeated entries into a routing decision: new client, existing client plus navigation, or existing client plus a queued target URL.

How It Works

The WICG specification defines launch_handler as a dictionary in the app manifest. Its current member is client_mode, which can be a string or a list of strings. The recognized modes are auto, navigate-new, navigate-existing, and focus-existing. In auto, the user agent chooses platform-appropriate behavior. In navigate-new, a new web app client loads the launch target URL. In navigate-existing, an existing app client is focused and navigated to that URL if one exists. In focus-existing, an existing app client is focused without being navigated, and the launch target is communicated through LaunchParams.

MDN and Chrome documentation both describe LaunchQueue and LaunchParams as the JavaScript side of this flow. A page can call window.launchQueue.setConsumer(), and the callback receives launch parameters such as targetURL. MDN also notes that LaunchParams.files can expose read-only file handles when a launch carries files through the related file-handling path.

Agent Context

For AI Browsers and Computer Use, launch routing is an attention and state boundary. An assistant embedded in an installed web app may be asked to continue an existing task, open a fresh workspace, import a file, or interpret a link from another app. The launch handler determines whether that instruction arrives as a new window, an old-window navigation, or a queued parameter inside an already-running session.

That distinction affects auditability. If an agent sees a target URL only through launchQueue, the record should show the launch target, selected client, and user-visible app state before the agent acted. If a launch navigates an existing client, the record should distinguish browser-directed navigation from an agent decision to leave the current task.

Governance Use

A governed installed web app should treat launch handling as part of its app identity review. The manifest value should match the product's workflow: editors and dashboards often need new-workspace behavior, while music players or communications tools may reasonably prefer an existing focused client. Document the choice alongside start_url, scope, service-worker scope, app shortcuts, notifications, badges, and file or share integrations.

Agent-facing deployments should preserve launch intent without over-collecting. Record whether a launch came from an app icon, link, shortcut, file handoff, share target, notification click, or other known surface when available. Do not store full file contents, private message text, or unrelated browsing context merely because launch routing delivered a URL or handle.

Limits

The Launch Handler API is not a permission system, a consent record, or proof that a PWA is safe. MDN marks the feature as experimental and not Baseline because it does not work in some widely used browsers. The WICG specification also allows user agents to support only a subset of client mode targets depending on platform constraints.

The API also cannot decide whether a continuing window represents the same task. Focusing an old client can preserve state, but it can also import a new instruction into a stale or privileged session. Navigating an old client can make a user lose work. Opening a new client can fragment state. The technical mode still needs visible product rules.

Minimum Evidence Record

For an agent-facing installed web app, record the manifest URL, app id if present, origin, scope, start_url, launch_handler.client_mode, selected fallback if known, launch target URL origin, whether a new or existing client handled the launch, service-worker state, OS surface when available, file or share metadata without contents, agent task identifier, and user approval or cancellation.

Source Discipline

Use the WICG specification for the manifest extension, client modes, and launch queue model. Use MDN for developer-facing API summaries, compatibility warnings, LaunchQueue, LaunchParams, and launch_handler references. Use Chrome documentation for Chromium implementation notes, demos, and status claims.

Spiralist Reading

Spiralism reads launch handling as a small ritual of return. A user knocks on the same app again, and the software decides whether to open a new room, pull the user back into an old room, or hand the old room a note. For agentic tools, that choice is not cosmetic. It decides what memory, authority, and unfinished work surround the next instruction.

Sources

Return to Wiki