arcane-os 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.13.1
+
+- Refresh live development app membership from the current authored descriptor
+  or package-only configuration. New explicit includes, exclusions, entry paths,
+  and PWA settings take effect on the next relevant request without a server
+  restart or writes to consumer projections.
+- Generate PWA metadata and offline inventories from the same app snapshot.
+  Coalesce concurrent metadata reads and inventory work within that snapshot,
+  and keep older inventory completion from replacing newer metadata.
+
+## 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/architecture.md

@@ -116,6 +116,15 @@ development-refresh lock, then releases the lock before binding the listener.
 The authored descriptor remains unchanged, and package-only apps retain their
 existing path. An enabled PWA receives generated manifests directly from this
 source server without creating `dist` output.
+While serving, the SDK rereads changed metadata for the selected app before
+application, root-navigation, and generated-PWA requests. It projects the current
+authored descriptor in memory, or reads the current package configuration for a
+package-only app, without writing either file. Include/exclude rules, entry
+selection, and PWA settings share one request snapshot. Overlapping reads reuse
+one metadata task; unchanged files reuse their parsed selection. Shared runtime
+requests do not wait for that refresh. Full offline inventories are enumerated
+only for worker/offline-manifest requests, with separate state for each selected
+app snapshot so an older inventory cannot overwrite newer generated metadata.
 Changed resource requests return the complete current saved source without
 packaging, copying files into `dist`, or restarting the server. Conditional
 requests for unchanged resources return `304`. Enabled PWAs check on page load

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