arcane-os 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.13.0
+
+- Add the reusable `pwa-install.html` component and shared browser installation
+  lifecycle through `arcane-os/pwa`. Offer a compact themed Install action and
+  explicit Close, retain session dismissal, support inline placement, and surface
+  native prompt errors without claiming installation completion.
+- Mount the component from generated PWA bootstraps independently of service
+  worker registration and application rendering. Use native installation and
+  display-mode events without polling, automatic native prompts, or focus capture.
+- Return cached resources immediately while conditional background refreshes
+  are pending or in flight, so page requests do not wait on network revalidation.
+- Document browser icon eligibility and the separate responsibilities of the
+  Web App Manifest, application file selection, and offline resource inventory.
+
 ## 0.12.0
 
 - Refresh the selected authored app descriptor's package projection before

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.12.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.13.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -30,6 +30,9 @@ page-load revalidation and persistent resource caches. The SDK records one
 completed-check timestamp per app/cache in DBOPFS and checks after 120 seconds
 in development or 15 minutes in packaged browser delivery. Apps retain ownership
 of branding, offline page selection and network-dependent product behavior.
+Enabled browser delivery also mounts the shared, themed installation suggestion.
+It appears when the browser offers installation, includes Install and Close,
+and remembers dismissal for the tab session without interrupting page startup.
 
 That registry query is a maintainer action, not an application behavior. Apps
 never poll npm for SDK updates or replace their own SDK or synchronized runtime.

package/browser-runtime/pwa-install.mjs

@@ -0,0 +1,242 @@
+import Is from './dependencies/strong-type/index.js';
+import {createArcaneEventSource} from './event-manager.mjs';
+
+const is = new Is(false);
+export const PWA_INSTALL_STATE_EVENT = 'arcane.pwa.install.state';
+let sharedOwner = null;
+let mountedPrompt = null;
+
+/** Capture native installation availability once per page, before loading UI. */
+export function getPwaInstall() {
+    if (sharedOwner && sharedOwner.state.status !== 'disposed') {
+        return sharedOwner;
+    }
+    const owner = {get state() { return snapshot(); }, subscribe, prompt, dismiss, dispose};
+    const source = createArcaneEventSource(owner, {
+        source: 'arcane.pwa.install', eventTypes: [PWA_INSTALL_STATE_EVENT]
+    });
+    const listeners = [];
+    const displayMode = globalThis.matchMedia?.(
+        '(display-mode: standalone), (display-mode: minimal-ui), '
+        + '(display-mode: fullscreen), (display-mode: window-controls-overlay)'
+    );
+    const manifestUrl = globalThis.document?.querySelector('link[rel~="manifest"]')?.href;
+    const dismissalKey = `arcane.pwa.install.dismissed:${manifestUrl ?? globalThis.location?.href ?? ''}`;
+    let deferredPrompt = null;
+    let disposed = false;
+    let dismissed = false;
+    let status = isRunningAsApp() ? 'running' : 'waiting';
+    let outcome = null;
+    let error = null;
+    try {
+        dismissed = globalThis.sessionStorage?.getItem(dismissalKey) === 'true';
+    } catch (storageError) {
+        console.warn('Arcane PWA install dismissal could not be read:', storageError);
+    }
+
+    function isRunningAsApp() {
+        return displayMode?.matches === true || globalThis.navigator?.standalone === true;
+    }
+
+    function snapshot() {
+        return {status, available: deferredPrompt !== null && !disposed,
+            dismissed, outcome, error};
+    }
+
+    function publish(nextStatus, nextError = null) {
+        if (disposed) return;
+        status = nextStatus;
+        error = nextError;
+        source.dispatch(PWA_INSTALL_STATE_EVENT, snapshot());
+    }
+
+    function observe(target, type, listener) {
+        if (!is.function(target?.addEventListener)) return;
+        target.addEventListener(type, listener);
+        listeners.push(function removeInstallListener() {
+            target.removeEventListener(type, listener);
+        });
+    }
+
+    function rememberDismissal() {
+        dismissed = true;
+        try {
+            globalThis.sessionStorage?.setItem(dismissalKey, 'true');
+        } catch (storageError) {
+            console.warn('Arcane PWA install dismissal could not be saved:', storageError);
+        }
+    }
+
+    function onBeforeInstallPrompt(event) {
+        if (disposed || isRunningAsApp() || status === 'installed' || status === 'accepted') return;
+        event.preventDefault();
+        deferredPrompt = event;
+        outcome = null;
+        publish('available');
+    }
+
+    function onInstalled() {
+        deferredPrompt = null;
+        // This event may precede Android's completion of WebAPK creation.
+        publish('installed');
+    }
+
+    function onDisplayModeChange() {
+        if (isRunningAsApp()) {
+            deferredPrompt = null;
+            publish('running');
+        } else if (status === 'running') {
+            publish('waiting');
+        }
+    }
+
+    function onPageHide(event) {
+        if (!event.persisted) dispose();
+    }
+
+    function subscribe(listener, {emitCurrent = true, signal} = {}) {
+        function forwardInstallState(event) { listener(event.detail); }
+        const unsubscribe = source.on(PWA_INSTALL_STATE_EVENT, forwardInstallState,
+            signal ? {signal} : undefined);
+        try {
+            if (emitCurrent && !signal?.aborted) listener(snapshot());
+        } catch (listenerError) {
+            unsubscribe();
+            throw listenerError;
+        }
+        return unsubscribe;
+    }
+
+    function prompt() {
+        if (disposed || !deferredPrompt) return Promise.resolve(null);
+        const event = deferredPrompt;
+        deferredPrompt = null;
+        publish('prompting');
+        let result;
+        try {
+            // Native user activation must reach prompt() in the same click stack.
+            result = event.prompt();
+        } catch (promptError) {
+            return rejectPrompt(promptError);
+        }
+        return Promise.resolve(result).then(async function receiveInstallChoice(value) {
+            const choice = value ?? await event.userChoice;
+            if (!choice || !['accepted', 'dismissed'].includes(choice.outcome)) {
+                throw new Error('The browser did not return an installation choice.');
+            }
+            if (!disposed) {
+                outcome = choice.outcome;
+                if (status === 'installed' || status === 'running') {
+                    publish(status);
+                } else {
+                    if (outcome === 'dismissed') rememberDismissal();
+                    publish(outcome);
+                }
+            }
+            return choice;
+        }).catch(rejectPrompt);
+    }
+
+    function rejectPrompt(promptError) {
+        if (status !== 'installed' && status !== 'running') publish('error', promptError);
+        return Promise.reject(promptError);
+    }
+
+    function dismiss() {
+        if (disposed) return snapshot();
+        rememberDismissal();
+        publish(status, error);
+        return snapshot();
+    }
+
+    function dispose() {
+        if (disposed) return;
+        deferredPrompt = null;
+        publish('disposed');
+        disposed = true;
+        for (const removeListener of listeners) removeListener();
+        listeners.length = 0;
+        source.dispose();
+    }
+
+    observe(globalThis, 'beforeinstallprompt', onBeforeInstallPrompt);
+    observe(globalThis, 'appinstalled', onInstalled);
+    observe(displayMode, 'change', onDisplayModeChange);
+    observe(globalThis, 'pagehide', onPageHide);
+    sharedOwner = owner;
+    return owner;
+}
+
+/** Mount one shared, initially hidden install component without delaying the app. */
+export function mountPwaInstallPrompt({appName = ''} = {}) {
+    const owner = getPwaInstall();
+    if (mountedPrompt) return mountedPrompt;
+    mountedPrompt = mountComponent().catch(function releaseFailedMount(error) {
+        mountedPrompt = null;
+        throw error;
+    });
+    return mountedPrompt;
+
+    async function mountComponent() {
+        if (!globalThis.document) return null;
+        // Both modules may start independently; saved theme loading is not a barrier.
+        await Promise.all([
+            import(new URL('../modules/HTMLImport.js', import.meta.url).href),
+            import(new URL('../modules/ThemeBootstrap.js', import.meta.url).href)
+        ]);
+        if (owner.state.status === 'disposed') return null;
+        if (!document.body) {
+            await new Promise(function waitForComponentParent(resolve) {
+                const unsubscribe = owner.subscribe(function observeParentWaitDisposal(state) {
+                    if (state.status === 'disposed') completeParentWait();
+                }, {emitCurrent: false});
+                function completeParentWait() {
+                    document.removeEventListener('DOMContentLoaded', completeParentWait);
+                    unsubscribe();
+                    resolve();
+                }
+                document.addEventListener('DOMContentLoaded', completeParentWait, {once: true});
+            });
+        }
+        if (owner.state.status === 'disposed') return null;
+        const host = document.createElement('html-import');
+        host.hidden = true;
+        host.dataset.appName = String(appName);
+        host.dataset.arcanePwaInstall = '';
+        host.setAttribute('href', new URL('../components/pwa-install.html', import.meta.url).href);
+        return new Promise(function waitForInstallComponent(resolve, reject) {
+            const observer = new MutationObserver(function observeRemovedInstallComponent() {
+                if (!host.isConnected) cancelMount();
+            });
+            const unsubscribe = owner.subscribe(function observeDisposedInstallOwner(state) {
+                if (state.status === 'disposed') cancelMount();
+            }, {emitCurrent: false});
+            function cleanup() {
+                observer.disconnect();
+                unsubscribe();
+                host.removeEventListener('html-import-ready', onReady);
+                host.removeEventListener('html-import-error', onError);
+            }
+            function cancelMount() {
+                cleanup();
+                host.remove();
+                const error = new Error('The PWA install component was removed before it became ready.');
+                error.name = 'AbortError';
+                reject(error);
+            }
+            function onReady() {
+                cleanup();
+                resolve(host);
+            }
+            function onError(event) {
+                cleanup();
+                host.remove();
+                reject(event.detail?.error ?? new Error('The PWA install component could not load.'));
+            }
+            host.addEventListener('html-import-ready', onReady);
+            host.addEventListener('html-import-error', onError);
+            document.body.append(host);
+            observer.observe(document.documentElement, {childList: true, subtree: true});
+        });
+    }
+}

package/browser-runtime/pwa.mjs

@@ -1,5 +1,7 @@
 import {createArcaneEventSource} from './event-manager.mjs';
 
+export {PWA_INSTALL_STATE_EVENT, getPwaInstall, mountPwaInstallPrompt} from './pwa-install.mjs';
+
 export const PWA_STATE_EVENT = 'arcane.pwa.state';
 
 export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {

package/docs/reference/inventory/package-api.json

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 205,
+  "memberCount": 208,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -2996,6 +2996,48 @@
       "protocol": "Native registration, updatefound, statechange and controllerchange events",
       "normalization": "Synchronous owner exposes ready, state, subscribe, update and dispose; current state replays by default, failures remain observable, disposal does not unregister the worker or delete saved data."
     },
+    {
+      "id": "pwa:PWA_INSTALL_STATE_EVENT",
+      "name": "PWA_INSTALL_STATE_EVENT",
+      "displayName": "PWA_INSTALL_STATE_EVENT",
+      "kind": "constant",
+      "signature": "const PWA_INSTALL_STATE_EVENT",
+      "entrypoints": ["arcane-os/pwa"],
+      "primaryImport": "arcane-os/pwa",
+      "group": "Progressive web applications",
+      "summary": "Names the shared native installation availability and choice state event.",
+      "availability": "Browser installation lifecycle; importable without starting observation",
+      "protocol": "Existing Arcane event owner and native browser installation events",
+      "normalization": "The exact event name is arcane.pwa.install.state."
+    },
+    {
+      "id": "pwa:getPwaInstall",
+      "name": "getPwaInstall",
+      "displayName": "getPwaInstall()",
+      "kind": "function",
+      "signature": "getPwaInstall()",
+      "entrypoints": ["arcane-os/pwa"],
+      "primaryImport": "arcane-os/pwa",
+      "group": "Progressive web applications",
+      "summary": "Returns one shared page owner for native installation availability, prompt choices and session dismissal.",
+      "availability": "Browser native installation events; waiting state while no prompt is available",
+      "protocol": "Native beforeinstallprompt, appinstalled and display-mode change events",
+      "normalization": "Synchronous owner exposes state, subscribe, prompt, dismiss and dispose; subscriptions replay current state, prompt invokes the native event directly in the user click and consumes it once, and session dismissal preserves a retained event for explicit inline installation."
+    },
+    {
+      "id": "pwa:mountPwaInstallPrompt",
+      "name": "mountPwaInstallPrompt",
+      "displayName": "mountPwaInstallPrompt()",
+      "kind": "function",
+      "signature": "mountPwaInstallPrompt({appName = ''} = {})",
+      "entrypoints": ["arcane-os/pwa"],
+      "primaryImport": "arcane-os/pwa",
+      "group": "Progressive web applications",
+      "summary": "Starts shared installation observation and mounts one initially hidden, themed installation suggestion without delaying application rendering.",
+      "availability": "Browser document and managed HTML import; resolves to null without a document",
+      "protocol": "Shared native install owner and pwa-install.html component lifecycle",
+      "normalization": "Repeated calls return the same mounting promise; the first appName initializes the component, success resolves to its ready html-import host, absence of a document or disposal before mounting resolves to null, and component loading failures reject. Removal or disposal during loading rejects with AbortError. A rejected mount permits another explicit attempt. Generated PWA bootstraps invoke it automatically."
+    },
     {
       "id": "browser-speech:BROWSER_SPEECH_ARTIFACT_GRAPH_PROTOCOL",
       "name": "BROWSER_SPEECH_ARTIFACT_GRAPH_PROTOCOL",

package/docs/reference/inventory/runtime-components.json

@@ -7,7 +7,7 @@
     "path": "runtime/arcane/components",
     "sdkVersion": "0.7.2"
   },
-  "componentCount": 40,
+  "componentCount": 41,
   "loader": "/arcane/modules/HTMLImport.js",
   "artifacts": [
     {
@@ -645,6 +645,34 @@
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
       "normalization": "Normalized form values"
     },
+    {
+      "file": "runtime/arcane/components/pwa-install.html",
+      "name": "pwa-install.html",
+      "purpose": "Presents a dismissible browser installation action with floating or inline placement.",
+      "methods": [
+        "configure()",
+        "install()",
+        "dismiss()",
+        "destroy()",
+        "state",
+        "ready"
+      ],
+      "events": [
+        "pwa-install-ready",
+        "pwa-install-change",
+        "pwa-install-dismissed"
+      ],
+      "slots": [],
+      "dependencies": [
+        "strong-type",
+        "arcane-os/pwa",
+        "arcane-os/event-manager",
+        "arcane-os/logging"
+      ],
+      "availability": "Browser installation requires a browser-provided beforeinstallprompt event; otherwise hidden",
+      "transport": "HTMLImport + DOM; shared PWA installation owner and browser-native prompt",
+      "normalization": "Browser install availability and outcome supplied by the shared PWA owner"
+    },
     {
       "file": "runtime/arcane/components/record-timeline.html",
       "name": "record-timeline.html",

package/docs/reference/pwa.md

@@ -2,7 +2,9 @@
 
 An application supplies its installation identity and offline resource selection.
 The SDK generates the Web App Manifest, offline inventory, service worker and
-nonblocking registration module. Native packages keep their existing lifecycle.
+nonblocking registration module. Its shared installation owner and dismissible
+component expose the browser's available install action. Native packages keep
+their existing lifecycle.
 
 ## Application configuration
 
@@ -63,7 +65,7 @@ Browser packaging emits these files at the selected deployment root:
 | `arcane.webmanifest` | Browser installation metadata. |
 | `arcane-offline.json` | App ID/version, SDK version, deployment revision, resource URLs and explicit navigation aliases. |
 | `arcane-sw.js` | Stable worker URL with the selected offline manifest embedded in its source. |
-| `arcane-pwa.mjs` | Independent registration module importing the SDK client. |
+| `arcane-pwa.mjs` | Independent registration and installation-component bootstrap importing the SDK client. |
 
 Each packaged output gets one deployment revision shared by its offline
 manifest and worker. It distinguishes separately generated outputs even when
@@ -74,6 +76,9 @@ It follows actual resource references to include meaningful query variants.
 Generated application pages receive a manifest link and an `async` module
 marked `data-arcane-pwa`. Existing application scripts retain their order.
 PWA registration does not wait for models, storage, preferences or page rendering.
+The same bootstrap starts one initially hidden `pwa-install.html` component with
+the generated manifest's app name. Component loading and worker registration
+proceed independently.
 
 The selected PWA browser delivery removes `v` and `arcaneVersion` from actual
 local resource references, including the managed import map. Other query fields,
@@ -91,7 +96,10 @@ Package-only applications retain their existing descriptor workflow.
 
 Add a file or directory to `package.include` to make it part of the app's
 resources. A new file inside an already included directory needs no separate
-entry. If `package.pwa.offline.include` is nonempty, the resource must also
+entry. `package.include` is an application resource selection, not a file list
+inside the Web App Manifest. `arcane.webmanifest` contains browser installation
+metadata; `arcane-offline.json` contains the selected offline resource inventory.
+If `package.pwa.offline.include` is nonempty, the resource must also
 match that offline selection and must not match `offline.exclude`. Adding a
 path only to the offline selection does not add it to the app's resources.
 Restart after changing descriptor settings. Edits to selected source files are
@@ -104,6 +112,8 @@ and packaged-preview serving, including conditional resource responses.
 Every Arcane development server and packaged browser preview serves HTTPS,
 including localhost. Configure the workspace certificate pair before starting
 the ordinary command; see [development HTTPS setup](cli.md#development-https-setup).
+`--public` selects the IPv4 wildcard bind address; it does not enable PWA
+configuration, change manifest metadata, or determine browser installability.
 
 Source inventory work begins when the browser requests the worker or current
 offline manifest, after the page can start. It traverses the selected route
@@ -153,7 +163,15 @@ the previous timestamp so the next page load can retry. Each cached response
 retains its own `Last-Modified` header, but there are no per-file check times.
 The SDK imposes no age-based cache deletion and
 retains resource bodies across app and SDK version changes. Requests for a page
-do not wait for the complete resource inventory to finish checking. The SDK
+do not wait for the complete resource inventory to finish checking. A file
+already in the current resource cache also returns immediately when its own
+conditional check is pending or in flight. That background check keeps its
+existing owner and updates the stored response for subsequent requests.
+The page receives the cached response's original status, commonly `200`, even
+when the separate conditional network response is `304`. Status alone does
+not identify a network transfer; use the browser's response source and timing
+details to distinguish cache access from worker startup, queueing and network.
+The SDK
 uses at most four concurrent background resource requests and starts no timer
 or polling loop between page loads.
 
@@ -205,6 +223,151 @@ Switching a server from a packaged release to live development does not replace
 an already active release worker inside an open document. The same native
 worker lifecycle applies.
 
+## Installation component
+
+Starting with SDK `0.13.0`, enabled PWA pages automatically mount the shared
+[`pwa-install.html` component](runtime-components.md#pwa-installhtml). It appears
+when the browser supplies an installation prompt, offers **Install** and a
+clearly labeled close control, and does not move focus when it appears.
+The floating suggestion has no automatic dismissal timer. Closing it remembers
+the choice for the current tab session and manifest URL, so another page
+load does not immediately show it again. A storage failure leaves the current
+page's dismissal functional and reports the error through console diagnostics.
+
+An application can also place the same component inline through `html-import`
+with `data-presentation="inline"`. Both presentations share one page-owned
+native installation event. Dismissing the floating suggestion does not consume
+that event or disable an explicitly placed inline component. Closing an inline
+instance hides only that instance. See the component reference for its
+configuration, methods and events.
+
+The browser controls the URL-bar installation indicator and native prompt.
+The SDK cannot force either to appear. Without a captured
+`beforeinstallprompt`, the component remains hidden; that waiting state does
+not establish that installation is unsupported. The browser may still be
+evaluating the app, may already have it installed, or may only support a
+manual browser-menu installation path.
+
+### Browser installation requirements
+
+Inspect the loaded page's manifest link and the browser's manifest diagnostics
+when an install action is missing. Confirm that the generated manifest has the
+intended name, `start_url`, scope and app display mode, and that its icon URLs
+resolve to actual images with the declared dimensions. For Chromium's manifest
+install promotion, provide a `purpose: "any"` icon, or omit `purpose` to use
+that default, in PNG, SVG or WebP format. Its strict installation icon selector
+excludes JPEG even when the same image renders successfully on the page.
+Do not change a file's extension or MIME declaration without converting the
+actual image at the application's asset owner. See Chromium's
+[icon selection implementation](https://raw.githubusercontent.com/chromium/chromium/main/third_party/blink/common/manifest/manifest_icon_selector.cc).
+
+Providing 192-by-192 and 512-by-512 raster icons follows the
+[browser guidance](https://web.dev/articles/add-manifest). Their absence alone
+does not prove the failure: Chromium can select one larger supported icon.
+Keep actual icon dimensions in `sizes`. Browser diagnostics about missing
+`screenshots` concern the richer installation dialog; screenshots are optional
+and are separate from a usable installation icon.
+
+Browser installation requires HTTPS or the browser's localhost/loopback
+exception. A device-facing LAN address is not loopback. Arcane's development
+server still follows its own HTTPS serving contract above. Browser engagement,
+installation state and platform support also affect whether native promotion
+appears; worker cache readiness is not an installation UI prerequisite. See
+[browser installation requirements](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable).
+
+Browsers without `beforeinstallprompt` can offer manual installation. For
+example, current iPhone Safari uses Share, **Add to Home Screen**, **Open as
+Web App**, then **Add**. A product may explain that browser-owned path in its
+help, but should not present it as a programmatic SDK install action. The SDK
+does not infer installation support from the user-agent string. See
+[Apple's installation instructions](https://support.apple.com/guide/iphone/open-as-web-app-iphea86e5236/ios).
+
+## getPwaInstall()
+
+Import `getPwaInstall` and `PWA_INSTALL_STATE_EVENT` from `arcane-os/pwa`.
+`getPwaInstall()` synchronously returns the shared page owner with `state`,
+`subscribe`, `prompt`, `dismiss` and `dispose`. Call it early when owning a
+separate install entry point so it can capture `beforeinstallprompt` before
+loading the UI. The generated bootstrap already does this through
+`mountPwaInstallPrompt()`.
+
+`state` contains `status`, `available`, `dismissed`, `outcome` and `error`.
+Status is `waiting`, `available`, `prompting`, `accepted`, `dismissed`,
+`installed`, `running`, `error` or `disposed`. `available` means a native event
+is retained; a dismissed floating suggestion can still have `available: true`.
+`outcome` is the browser's `accepted` or `dismissed` choice, or `null` before a
+choice. `error` carries the complete prompt error, or `null`.
+
+`subscribe(listener, {emitCurrent: true, signal} = {})` immediately replays
+state by default and returns an unsubscribe function. Later state travels
+through the existing Arcane event owner using `PWA_INSTALL_STATE_EVENT`
+(`arcane.pwa.install.state`). A subscription does not wait for worker
+registration, storage initialization or model readiness.
+
+Call `prompt()` directly from the user's install click, before any asynchronous
+wait. It invokes the browser prompt in the same call stack, consumes the event
+once, and returns a promise for the browser's choice. It resolves to `null`
+when there is no retained event or the owner is disposed. Failure publishes
+`error` state and rejects. A new native event is required for another prompt.
+
+```javascript
+import {getPwaInstall} from 'arcane-os/pwa';
+
+const install = getPwaInstall();
+const installButton = document.querySelector('#install');
+
+install.subscribe(function showInstallAvailability(state) {
+    installButton.hidden = !state.available;
+});
+installButton.addEventListener('click', function requestInstallation() {
+    install.prompt().catch(function reportInstallFailure(error) {
+        console.error(error);
+    });
+});
+```
+
+`dismiss()` remembers the session choice without consuming the retained event
+and returns the current state. A browser-native dismissed choice is remembered
+too. `appinstalled` clears the event and publishes `installed`; running in an
+app display mode publishes `running` and suppresses the prompt. These states
+do not establish offline readiness. On Android, `appinstalled` can arrive
+before WebAPK creation finishes. See the
+[browser lifecycle distinction](https://web.dev/learn/pwa/detection/).
+
+`dispose()` removes the shared owner's native listeners and subscriptions.
+Leaving the page disposes it automatically, except when the browser retains
+the page in its back/forward cache.
+Because the owner is shared, an individual component should dispose its own
+subscription instead. A later `getPwaInstall()` creates a new owner after
+disposal; it cannot recover a native event that was already consumed.
+
+## mountPwaInstallPrompt()
+
+`mountPwaInstallPrompt({appName = ''} = {})` starts native install observation
+synchronously, then loads the shared HTML import and theme modules concurrently
+and appends one initially hidden component when the document body is available.
+It returns the same mounting promise on repeated calls; the first call supplies
+the initial app name. The promise resolves to the ready `html-import` host, or
+`null` without a document or when the owner is disposed before mounting. It
+rejects if component loading fails, or with `AbortError` when the loading host
+is removed or its owner disposed. A rejected mount releases its slot so an
+explicit later call can try again. Observe the rejection without making page
+rendering wait for it.
+
+The generated PWA bootstrap calls this automatically using the manifest name.
+Applications need not add another floating suggestion. A separate entry point
+can call it explicitly:
+
+```javascript
+import {mountPwaInstallPrompt} from 'arcane-os/pwa';
+
+mountPwaInstallPrompt({appName: 'Example Library'}).catch(
+    function reportInstallComponentFailure(error) {
+        console.error(error);
+    }
+);
+```
+
 ## registerPwa()
 
 Import `registerPwa` and `PWA_STATE_EVENT` from `arcane-os/pwa` through the

package/docs/reference/runtime-components.md

@@ -82,6 +82,7 @@ appropriate.
 | [`modal.html`](#modalhtml) | Generic modal with population, open/close, actions, and sequential task execution. | `populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
 | [`output-panel.html`](#output-panelhtml) | Presents status, output, body, coverage, actions, pending, error, and cleared states. | `configure()`<br>`setOutput()`<br>`setBody()`<br>`setCoverage()`<br>`setActions()`<br>`setPending()`<br>`setStatus()`<br>`setError()`<br>`clear()`<br>`destroy()` | `output-panel-ready`<br>`output-panel-state`<br>`output-panel-change`<br>`output-panel-action`<br>`output-panel-error`<br>`output-panel-cleared` | DOM-normalized |
 | [`preferences-form.html`](#preferences-formhtml) | Builds a schema-driven preferences form with submit, reset, busy, and status behavior. | `configure()`<br>`getValues()`<br>`setValues()`<br>`setBusy()`<br>`setStatus()`<br>`destroy()` | `preferences-form-ready`<br>`preferences-change`<br>`preferences-submit`<br>`preferences-reset` | Normalized form values |
+| [`pwa-install.html`](#pwa-installhtml) | Presents a dismissible browser installation action with floating or inline placement. | `configure()`<br>`install()`<br>`dismiss()`<br>`destroy()`<br>`state`<br>`ready` | `pwa-install-ready`<br>`pwa-install-change`<br>`pwa-install-dismissed` | Browser install availability and outcome supplied by the shared PWA owner |
 | [`record-timeline.html`](#record-timelinehtml) | Displays complete chronological records/evidence and emits open actions. | `setItems()`<br>`populate()`<br>`destroy()` | `record-timeline-ready`<br>`record-timeline-open` | Complete item fields and inventories preserved |
 | [`relationship-board.html`](#relationship-boardhtml) | Displays complete normalized relationship nodes/edges in graph and list forms. | `setGraph()`<br>`populate()`<br>`destroy()` | `relationship-board-ready`<br>`relationship-node-open`<br>`relationship-edge-open` | Complete graph inventories and fields preserved |
 | [`screen-capture.html`](#screen-capturehtml) | Presents image, video, or GIF display-capture workflow. | `capture` (`ScreenCapture` instance)<br>`destroy()` | `screen-capture-ready`<br>`screen-capture-result` | State/result normalized; media permission/codec failures mixed |
@@ -1018,6 +1019,69 @@ Events: `preferences-form-ready`, `preferences-change`, `preferences-submit`, `p
 </html-import>
 ```
 
+## pwa-install.html
+
+### Overview
+
+A compact installation suggestion using the shared [PWA installation owner](pwa.md).
+The default floating panel appears near the top right only when the browser offers
+installation. It has an Install action and an explicit close button, takes no
+focus automatically, and has no dismissal timer. It uses the Arcane theme and
+primitives, wraps complete labels and errors, and scrolls its own content when
+the available height is limited. The parent page loads `ThemeBootstrap.js` to
+apply the user's appearance preferences.
+
+### Public surface
+
+`configure({appName, installLabel, closeLabel, promptingLabel, description,
+presentation})` updates display configuration and returns its current record.
+Labels remain complete strings. `appName` initially uses `data-app-name` or
+`this app`; the default button label is `Install`. `presentation` is `floating`
+by default or `inline`, initially read from `data-presentation`. Inline placement
+uses the parent's layout. Set `description` to an empty string when a compact
+placement needs no supporting text; supplied descriptions remain visible.
+
+`install()` calls the shared owner's native prompt synchronously and returns its
+promise of the browser outcome or `null` when no prompt is available. Call it
+directly from a user action. The component's Install button already does this.
+An explicit request's complete failure message remains visible until dismissed;
+the method rejects with the same error. The browser controls actual installation.
+Acceptance hides the suggestion without claiming installation has completed.
+
+`dismiss()` closes the component. Floating dismissal also uses the owner's
+session dismissal; an explicit inline component ignores that shared dismissal
+and closes only its own instance. Closing retains any unused native prompt at
+the shared owner. `destroy()` removes the component's listeners and subscription,
+disposes its event source, hides its host, and marks `ready` false; it does not
+dispose the shared owner or change browser installation state. Both methods
+return true while active and false after destruction; `destroy()` is idempotent.
+
+The readonly `state` property returns the shared owner's current install-state
+record; `ready` becomes true after methods and the state subscription are attached.
+`pwa-install-ready` carries `{ready, state}`; `pwa-install-change` carries
+`{state, visible}` for each observed owner update; `pwa-install-dismissed` carries
+`{presentation, state}`. These follow the canonical event projection contract.
+
+### Availability and normalization
+
+The component requires HTMLImport and a DOM renderer. Native installation
+availability comes from the browser's `beforeinstallprompt` event through
+`getPwaInstall()`. Without an available event, the suggestion stays hidden;
+absence does not identify why installation is unavailable. Installed-app events,
+accepted prompts, and an already running installed display mode hide it.
+
+### Example
+
+```html
+<html-import
+  id="install-app"
+  href="/arcane/components/pwa-install.html"
+  data-app-name="Example Library"
+  data-presentation="inline"
+  hidden>
+</html-import>
+```
+
 ## record-timeline.html
 
 ### Overview

package/docs/reference/sdk-api.md

@@ -39,7 +39,7 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/speech-playback` | Portable speech preparation, playback state, and injected media adapters. |
 | `arcane-os/speech-text` | Speech-input formatting cleanup for complete text and streamed chunks. |
 | `arcane-os/browser-device` | Synchronous mobile or desktop identity hints for application-owned settings. |
-| `arcane-os/pwa` | Nonblocking PWA registration, native worker updates and observable lifecycle state. |
+| `arcane-os/pwa` | Nonblocking PWA registration, worker updates, native installation state and a dismissible installation component. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
@@ -129,6 +129,9 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `getBrowserDeviceClass()` | function | `arcane-os/browser-device` | Browser device settings | Node and Browser; synchronous identity hint with no model, storage, or GPU operation |
 | `PWA_STATE_EVENT` | constant | `arcane-os/pwa` | Progressive web applications | Browser lifecycle event name; importable without registration |
 | `registerPwa()` | function | `arcane-os/pwa` | Progressive web applications | Browser service workers; synchronous unsupported state when unavailable |
+| `PWA_INSTALL_STATE_EVENT` | constant | `arcane-os/pwa` | Progressive web applications | Browser installation event name; importable without starting observation |
+| `getPwaInstall()` | function | `arcane-os/pwa` | Progressive web applications | Browser native installation events; waiting state while no prompt is available |
+| `mountPwaInstallPrompt()` | function | `arcane-os/pwa` | Progressive web applications | Browser document and managed HTML import; resolves to null without a document |
 | `createDbopfsSpeechArtifactStore()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser with ready DBOPFS, Web Locks, Fetch, File/Blob, and object URLs |
 | `removeBrowserSpeechModelCache()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser CacheStorage; explicit removal of one selected upstream model |
 | `createNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -6124,6 +6127,99 @@ current-state replay, disposal, offline resource ownership and update behavior.
 The generated bootstrap registers automatically; a manual caller owns a separate
 entry point and must observe its `ready` rejection.
 
+## PWA_INSTALL_STATE_EVENT
+
+### Overview
+
+The exact event name `arcane.pwa.install.state` identifies native installation
+availability and choice state through the existing Arcane event owner. It is
+separate from service-worker registration state. Importing it starts no
+observation or installation.
+
+### Example
+
+```javascript
+import {PWA_INSTALL_STATE_EVENT} from 'arcane-os/pwa';
+console.log(PWA_INSTALL_STATE_EVENT);
+```
+
+See the [installation state contract](pwa.md#getpwainstall) for the complete
+payload and current-state subscription behavior.
+
+## getPwaInstall()
+
+### Overview
+
+`getPwaInstall()` returns one synchronous page owner exposing `state`,
+`subscribe`, `prompt`, `dismiss` and `dispose`. It captures the browser's
+`beforeinstallprompt` event and observes `appinstalled` and app display-mode
+changes. A missing event leaves installation availability unknown and the owner
+waiting; it does not prove browser incompatibility.
+
+State contains `status`, `available`, `dismissed`, `outcome` and `error`.
+Subscriptions replay current state by default. `prompt()` must be called
+directly within the install click to preserve native user activation. It
+consumes the event once and returns the browser choice, resolves to `null` when
+unavailable, or rejects with the actual error. `dismiss()` remembers the
+session's floating-suggestion dismissal without consuming a retained event.
+
+### Example
+
+```javascript
+import {getPwaInstall} from 'arcane-os/pwa';
+
+const install = getPwaInstall();
+const button = document.querySelector('#install');
+install.subscribe(function updateInstallButton(state) {
+    button.hidden = !state.available;
+});
+button.addEventListener('click', function requestInstallation() {
+    install.prompt().catch(function reportInstallFailure(error) {
+        console.error(error);
+    });
+});
+```
+
+The [PWA guide](pwa.md#getpwainstall) defines every status, event lifetime,
+session dismissal, errors and disposal. Disposing this shared owner removes
+its page-level observation; components normally unsubscribe only their own
+listener. Installation state does not establish offline readiness or completed
+Android WebAPK creation.
+
+## mountPwaInstallPrompt()
+
+### Overview
+
+`mountPwaInstallPrompt({appName = ''} = {})` starts the shared install observer
+before asynchronously mounting one initially hidden `pwa-install.html`
+component. Repeated calls return the same mounting promise. It resolves to the
+ready `html-import` host, or `null` without a document or when the owner is
+disposed before mounting. Component-load failure rejects; removal or disposal
+during loading rejects with `AbortError`. A rejected mount permits another
+explicit attempt. The first call
+supplies the initial app name.
+
+The generated PWA bootstrap calls this automatically with the manifest name.
+Component mounting and worker registration run independently, and application
+rendering must not await them. The floating component offers Install and a
+manual close control; an application can also place the same component inline.
+
+### Example
+
+```javascript
+import {mountPwaInstallPrompt} from 'arcane-os/pwa';
+
+mountPwaInstallPrompt({appName: 'Example Library'}).catch(
+    function reportInstallComponentFailure(error) {
+        console.error(error);
+    }
+);
+```
+
+See the [mounting contract](pwa.md#mountpwainstallprompt) and
+[component reference](runtime-components.md#pwa-installhtml). The browser owns
+native installation eligibility and URL-bar promotion.
+
 ## createBrowserWasmLlmProvider()
 
 ### Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -67,7 +67,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/components/pwa-install.html

@@ -0,0 +1,216 @@
+<link rel="stylesheet" href="./arcane/css/theme.css?v=1">
+<link rel="stylesheet" href="./arcane/css/primitives.css?v=1">
+<style>
+    :host{
+        display:block;
+        inset-block-start:4.5rem;
+        inset-inline-end:1rem;
+        max-width:calc(100vw - 2rem);
+        min-width:0;
+        position:fixed;
+        width:22rem;
+        z-index:110;
+    }
+    :host([hidden]){display:none}
+    :host([data-presentation="inline"]){
+        max-width:100%;
+        position:static;
+        width:fit-content;
+    }
+    .panel{
+        background:var(--arcane-surface-raised);
+        border:1px solid var(--arcane-border);
+        border-radius:var(--arcane-radius-medium);
+        box-shadow:var(--arcane-shadow-medium);
+        box-sizing:border-box;
+        color:var(--text-color);
+        display:grid;
+        gap:var(--arcane-space-2);
+        max-height:calc(100vh - 5.5rem);
+        max-height:calc(100dvh - 5.5rem);
+        overflow:auto;
+        padding:var(--arcane-space-3);
+    }
+    .heading{align-items:start;display:flex;gap:var(--arcane-space-2)}
+    .copy{flex:1;min-width:0}
+    h2,p{margin:0;overflow-wrap:anywhere;white-space:pre-wrap}
+    h2{font-size:1rem;line-height:1.4}
+    .description{color:var(--arcane-muted);font-size:.9rem;line-height:1.45}
+    .close{flex:none}
+    .install{justify-self:start;max-width:100%;overflow-wrap:anywhere;white-space:normal}
+    .status{font-size:.9rem;line-height:1.45}
+    .status[data-error="true"]{color:var(--arcane-danger)}
+    :host([data-presentation="inline"]) .panel{box-shadow:none}
+    @media(prefers-reduced-motion:reduce){.install{transition:none}}
+    @media(forced-colors:active){.panel,.install,.close{border:1px solid CanvasText}}
+</style>
+
+<section class="panel" aria-labelledby="installTitle">
+    <div class="heading">
+        <div class="copy">
+            <h2 id="installTitle">Install this app</h2>
+            <p id="description" class="description">Open this app directly from your device.</p>
+        </div>
+        <button id="close" class="close arcane-close-button" type="button" aria-label="Close installation suggestion">&#x2715;</button>
+    </div>
+    <button id="install" class="install arcane-button" type="button">Install</button>
+    <p id="status" class="status" role="status" aria-live="polite" hidden></p>
+</section>
+
+<script type="module">
+    const host=this;
+    host.hidden=true;
+    const [
+        {default:Is},
+        {getPwaInstall},
+        {createArcaneEventSource,projectArcaneDOMEvent},
+        {arcaneLogging}
+    ]=await Promise.all([
+        import('strong-type'),
+        import('arcane-os/pwa'),
+        import('arcane-os/event-manager'),
+        import('arcane-os/logging')
+    ]);
+    const is=new Is(false);
+    const root=host.shadowRoot;
+    const title=root.querySelector('#installTitle');
+    const description=root.querySelector('#description');
+    const installButton=root.querySelector('#install');
+    const closeButton=root.querySelector('#close');
+    const status=root.querySelector('#status');
+    const lifecycleController=new AbortController();
+    const events=createArcaneEventSource(host,{
+        source:'arcane.component.pwa-install',
+        eventTypes:['pwa-install-ready','pwa-install-change','pwa-install-dismissed']
+    });
+    const owner=getPwaInstall();
+    let options={
+        appName:host.dataset.appName||'this app',
+        installLabel:'Install',
+        closeLabel:'Close installation suggestion',
+        promptingLabel:'Choose an option in the browser installation prompt.',
+        description:'Open this app directly from your device.',
+        presentation:host.dataset.presentation||'floating'
+    };
+    let currentState=owner.state;
+    let locallyDismissed=false;
+    let pending=false;
+    let requestError=null;
+    let destroyed=false;
+
+    host.configure=configure;
+    host.install=install;
+    host.dismiss=dismiss;
+    host.destroy=destroy;
+    Object.defineProperty(host,'state',{configurable:true,get:getState});
+
+    function emit(type,detail){
+        if(destroyed)return false;
+        const publication=events.dispatch(type,detail);
+        return projectArcaneDOMEvent(host,publication.occurrence,{bubbles:true,composed:true});
+    }
+
+    function getState(){
+        return {...currentState};
+    }
+
+    function configure(input={}){
+        if(destroyed)return false;
+        if(input===null||!is.object(input)||is.array(input)){
+            throw new TypeError('PWA install configuration must be an object.');
+        }
+        const next={...options,...input};
+        for(const key of ['appName','installLabel','closeLabel','promptingLabel','description']){
+            if(!is.string(next[key]))throw new TypeError(`PWA install ${key} must be a string.`);
+        }
+        if(next.presentation!=='floating'&&next.presentation!=='inline'){
+            throw new TypeError('PWA install presentation must be floating or inline.');
+        }
+        options=next;
+        host.dataset.presentation=options.presentation;
+        title.textContent=`Install ${options.appName}`;
+        description.textContent=options.description;
+        installButton.textContent=options.installLabel;
+        closeButton.setAttribute('aria-label',options.closeLabel);
+        render();
+        return {...options};
+    }
+
+    function render(){
+        if(destroyed)return;
+        const terminal=['accepted','installed','running','disposed'].includes(currentState.status);
+        if(terminal)requestError=null;
+        const dismissed=locallyDismissed
+            ||(options.presentation==='floating'&&currentState.dismissed);
+        host.hidden=terminal||dismissed||(!currentState.available&&!pending&&!requestError);
+        installButton.disabled=pending||!currentState.available;
+        const message=requestError
+            ?is.string(requestError.message)?requestError.message:String(requestError)
+            :pending?options.promptingLabel:'';
+        status.textContent=message;
+        status.hidden=!message;
+        status.dataset.error=String(Boolean(requestError));
+    }
+
+    function observeInstallState(state){
+        if(destroyed)return;
+        currentState=state;
+        render();
+        emit('pwa-install-change',{state:getState(),visible:!host.hidden});
+    }
+
+    function install(){
+        if(destroyed||pending||!currentState.available)return Promise.resolve(null);
+        locallyDismissed=false;
+        requestError=null;
+        pending=true;
+        render();
+        let operation;
+        try{
+            // Keep the browser prompt inside the initiating click's user activation.
+            operation=owner.prompt();
+        }catch(error){
+            operation=Promise.reject(error);
+        }
+        return Promise.resolve(operation).catch(function reportPromptError(error){
+            if(!destroyed)requestError=error;
+            throw error;
+        }).finally(function settlePrompt(){
+            if(destroyed)return;
+            pending=false;
+            render();
+        });
+    }
+
+    function dismiss(){
+        if(destroyed)return false;
+        locallyDismissed=true;
+        requestError=null;
+        if(options.presentation==='floating')owner.dismiss();
+        render();
+        emit('pwa-install-dismissed',{presentation:options.presentation,state:getState()});
+        return true;
+    }
+
+    function destroy(){
+        if(destroyed)return false;
+        destroyed=true;
+        lifecycleController.abort('pwa-install-destroyed');
+        events.dispose();
+        host.hidden=true;
+        host.ready=false;
+        return true;
+    }
+
+    installButton.addEventListener('click',function requestInstallation(){
+        install().catch(function reportInstallationFailure(error){
+            arcaneLogging.error('Unable to open the browser installation prompt:',error);
+        });
+    },{signal:lifecycleController.signal});
+    closeButton.addEventListener('click',dismiss,{signal:lifecycleController.signal});
+
+    configure();
+    owner.subscribe(observeInstallState,{signal:lifecycleController.signal});
+    host.ready=true;
+    emit('pwa-install-ready',{ready:true,state:getState()});
+</script>

package/src/pwa-worker.mjs

@@ -403,12 +403,10 @@ function installPwaWorker(manifest, clientUrl) {
         if (!ownedUrls.has(url)) {
             return {response: await fetch(request), done: Promise.resolve(null)};
         }
-        if (!pendingChecks.has(url) && !resourceJobs.has(url)) {
-            const cache = await caches.open(cacheName);
-            const cached = await cache.match(url);
-            if (cached) {
-                return {response: cached, done: Promise.resolve(null)};
-            }
+        const cache = await caches.open(cacheName);
+        const cached = await cache.match(url);
+        if (cached) {
+            return {response: cached, done: Promise.resolve(null)};
         }
         const job = resourceJob(request, url, pendingChecks.has(url));
         return {response: resourceResponse(await job.result), done: job.done};

package/src/pwa.mjs

@@ -277,7 +277,13 @@ export function createPwaArtifacts(
         ),
         navigationAliases: navigationAliases ?? {[basePath]: app.entry}
     };
-    const bootstrap = `import {registerPwa} from ${JSON.stringify(`${runtimeBase}pwa.mjs`)};
+    const bootstrap = `import {registerPwa, mountPwaInstallPrompt} from ${JSON.stringify(`${runtimeBase}pwa.mjs`)};
+
+mountPwaInstallPrompt({appName: ${JSON.stringify(manifest.name)}}).catch(
+    function reportPwaInstallComponentFailure(error) {
+        console.error('Arcane PWA install component failed:', error);
+    }
+);
 
 const controller = registerPwa(
     {