arcane-os 0.11.3 → 0.13.0

package/docs/reference/cli.md

@@ -48,10 +48,11 @@ meaning and cardinality rules:
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
 | `--app` | app id | Workspace/app operations except shared scope and `verify-bundle`; also the exact `mail serve` caller id. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
-| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to `127.0.0.1:8000`; `mail serve` defaults to `127.0.0.1:8025` and admits numeric loopback only. |
+| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTP at `127.0.0.1:8025` and admits numeric loopback only. |
+| `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
 | `--public` | flag | `dev`; serves HTTPS and binds to `0.0.0.0` unless `--host` explicitly selects another address. |
-| `--https` | flag | `dev`; serves HTTPS with the configured or default workspace PEM pair. |
-| `--cert` / `--key` | PEM file paths | `dev`; supply both to select HTTPS with an explicit certificate chain and private key. Relative paths resolve from the workspace. |
+| `--https` | flag | Browser `dev`/`run`; retained explicitly, while HTTPS is always enabled. |
+| `--cert` / `--key` | PEM file paths | Browser `dev`/`run`; supply both for an explicit certificate chain and private key. Relative paths resolve from the workspace. |
 | `--target` | target id | `new`, `init`, native diagnostics, `build`, `run` |
 | `--format` / `--signing` | target-supported values | Native diagnostics, `build`, `run` |
 | `--output-root` | directory | Native `build` and `run` |
@@ -311,7 +312,7 @@ npm exec -- arcane upgrade --workspace . --app hello-world
 ### Overview
 
 Starts one development server for one selected app and maps the exact
-workspace/runtime routes. It defaults to localhost; `--public` enables access
+workspace/runtime routes. It defaults to HTTPS on localhost; `--public` enables access
 from other devices on the network over HTTPS.
 
 For an external workspace, the server exposes the selected projected
@@ -321,11 +322,19 @@ The explicit live-source SDK mapping remains unchanged and does not replace the
 installed projection.
 
 ```text
-arcane dev [--app <id>] [--public] [--https] [--cert <file> --key <file>] [--host <address>] [--port 8000]
+arcane dev [--app <id>] [--public] [--https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0]
 ```
 
 ### Lifecycle
 
+Startup refreshes the selected authored `arcane-app.json` projection into
+`arcane-package.json`, then refreshes its managed import maps under one
+development-refresh operation lock. The lock is released before the server
+starts. Package-only apps retain their existing manifest. This operation does
+not package the app or produce `dist` output. With PWA enabled, the server
+generates the installation and offline manifests directly; see
+[PWA development and versioning](pwa.md#development-and-hosting).
+
 The command reports acceptance before bind/start work, emits the final URL,
 owns the server until cancellation, and restores failure to the process exit.
 The default host is `127.0.0.1`. `--public` selects `0.0.0.0` (all IPv4
@@ -335,25 +344,33 @@ device, since `localhost` refers to that device and `0.0.0.0` is a bind address.
 Network URLs come from one interface snapshot at startup and do not establish
 remote reachability through the machine's firewall or network.
 
-Public mode also selects HTTPS. Plain localhost development stays HTTP.
-`--https` selects HTTPS without changing the bind address; supplying both
-`--cert` and `--key` also selects HTTPS. The command does not configure a
-firewall, router forwarding, or an internet tunnel.
+Every Arcane app uses HTTPS for development and packaged browser previews.
+`--https` remains accepted but is no longer needed to select the transport.
+`--port` selects the HTTPS application port. A second HTTP listener returns
+`308` redirects to that HTTPS port, preserving the requested path and query.
+`--http-port` selects its port; the default `0` lets the operating system choose
+an available port. Both listeners use the selected host and must be ready
+before startup completes. Cancellation or a listener failure closes both.
+Human output prints `HTTP redirect: <url>` alongside the HTTPS application URL;
+JSON/NDJSON server results include `httpPort`, `httpOrigin`, and `httpUrl` for
+the redirect endpoint.
+Supplying both `--cert` and `--key` selects an explicit PEM pair. The command
+does not configure a firewall, router forwarding, or an internet tunnel.
 
 ### Development HTTPS setup
 
-Before starting public mode, place the development server's PEM certificate
-chain at `.arcane/dev/server-cert.pem` and its PEM private key at
+Before starting `arcane dev` or a packaged browser preview, place the server's
+PEM certificate chain at `.arcane/dev/server-cert.pem` and its PEM private key at
 `.arcane/dev/server-key.pem`, relative to the workspace. Alternatively, pass
-`--cert <file> --key <file>` together. The certificate must cover the LAN IP
+`--cert <file> --key <file>` together. The certificate must cover localhost or the LAN IP
 address or hostname opened by each device. Certificate creation and renewal
 belong to the developer's certificate tooling; the server does not generate a
 CA or alter device trust stores. Keep `.arcane/dev/` ignored by Git and keep the
 private key on the development computer.
 
-The server reads the selected pair once asynchronously per startup, before
-binding. Missing files or certificate/key parse errors produce a startup error; public
-mode never silently falls back to HTTP. Certificate/key contents are not
+The server reads the selected pair during startup, before binding.
+Missing files or certificate/key parse errors produce a startup error;
+Arcane never silently falls back to HTTP. Certificate/key contents are not
 included in operation events or JSON/NDJSON output. Restart the server after
 replacing its certificate pair; ordinary app source edits still appear on
 refresh without restarting.
@@ -383,6 +400,9 @@ npm run dev -- --app hello-world --public
 
 # Equivalent direct CLI invocation, with an optional port.
 npm exec -- arcane dev --app hello-world --public --port 8000
+
+# Select a stable HTTP entry that redirects to HTTPS on port 8000.
+npm exec -- arcane dev --app hello-world --port 8000 --http-port 8080
 ```
 
 ## `arcane test`
@@ -617,11 +637,17 @@ npm exec -- arcane build \
 
 For `--target browser`, starts the existing current `dist/<app>` release; it
 does not package, rebuild, test, check, or verify that release automatically.
+The preview always uses HTTPS with the workspace certificate pair. Supply
+`--cert <file> --key <file>` together to use another pair; see
+[development HTTPS setup](#development-https-setup).
+`--port` selects the HTTPS application port, and `--http-port` selects the
+paired HTTP `308` redirect port. The HTTP port defaults to an available port;
+the CLI prints its actual redirect URL and reports both listener endpoints.
 For a paired native target, it performs package, prepare, plan, build, launch,
 readiness, and owned cancellation in one process.
 
 ```text
-arcane run [--target <target>] [--app <id>] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
+arcane run [--target <target>] [--app <id>] [--cert <file> --key <file>] [--port 8000] [--http-port 0] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
 ```
 
 ### Availability

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",
@@ -2991,11 +2991,53 @@
       "entrypoints": ["arcane-os/pwa"],
       "primaryImport": "arcane-os/pwa",
       "group": "Progressive web applications",
-      "summary": "Starts PWA registration without blocking page rendering and returns an observable lifecycle owner.",
+      "summary": "Starts PWA registration and DBOPFS-backed page-load resource checks without blocking rendering, returning an observable lifecycle owner.",
       "availability": "Browser service workers; explicit unsupported state elsewhere",
       "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,
@@ -83,31 +88,103 @@ the [existing asset version contract](asset-versioning.md).
 
 ## Development and hosting
 
+Use the ordinary `arcane dev --app <id>` command after editing the selected
+app's `arcane-app.json`. Startup refreshes that app's generated
+`arcane-package.json` from the authored descriptor before refreshing its import
+maps and starting the server. No packaging or `dist` output is required.
+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. `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
+picked up by the next due page-load check while the server remains running.
+
 For an enabled application, `arcane dev` serves the generated PWA files at the
 origin root and starts at the selected app page under `/apps/<id>/`. Use one
-selected app per development origin. Its worker uses network revalidation first
-and retains successful selected resource responses for offline use, so saved
-source edits remain visible on an ordinary online refresh.
-
-Source inventory work begins when the browser requests the worker update, after
-the page can start. It traverses the selected route inventory once for that
-request, follows application page and runtime resource references to retain
-selected query variants, and shares an in-flight traversal with concurrent
-manifest requests. Each referenced source file is read once per traversal;
+selected app per development origin. The SDK uses `node-http-server` for source
+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
+inventory once for that request, follows page and runtime resource references
+to retain selected query variants, and shares an in-flight traversal with
+concurrent requests. Each referenced source file is read once per traversal;
 document corpus bodies remain under their existing owner. It does not rebuild
-the application. Generated metadata and bootstrap requests reuse the current
-bundle.
+the application. Installation metadata and bootstrap requests reuse the current
+generated bundle.
+
+The SDK owns version information in `arcane-offline.json`:
+
+| Field | Owner and update rule |
+| --- | --- |
+| `schemaVersion` | SDK offline-manifest format; currently `1`. |
+| `appVersion` | The app descriptor's top-level `version`. |
+| `sdkVersion` | The selected installed SDK or explicit live SDK source version. |
+| `revision` | `development` for the source server; a fresh generated deployment ID for each packaged output. |
+
+Do not hand-edit generated manifests or bump a version for every source edit.
+`arcane.webmanifest` holds installation metadata and has no separate SDK-managed
+release counter. Resource freshness uses each response's `Last-Modified` header.
+
+On each page load, the SDK reads one `lastChecked` value for the app and worker
+scope from DBOPFS in the background. When that value is missing or older than
+the delivery mode's interval, it checks the current offline manifest and every
+selected resource:
 
-Packaged workers use their selected cache generation first. During installation,
-at most four resource requests run together; each response is fetched from the
-network with the browser's reload cache mode before it enters the candidate
-cache. The candidate must finish
-installation before the browser activates it. Failures retain the prior active
-worker and remain observable through native worker state and SDK diagnostics.
+| Mode | Page-load check interval |
+| --- | --- |
+| Development | 120 seconds |
+| Packaged browser delivery | 15 minutes |
+
+These intervals schedule revalidation; they never expire a cached file. The
+worker sends `GET` with `If-Modified-Since` using the cached response's
+`Last-Modified`. A `304 Not Modified` retains the complete cached response. A
+successful `200` replaces it after the new response is stored. Missing cached
+resources are downloaded. Network and server failures retain an existing
+offline copy and remain observable through SDK diagnostics. A host without
+modification headers must send the current response because freshness cannot
+be established from a missing header.
+
+Complete resource responses remain in browser CacheStorage. DBOPFS stores one
+successful whole-cycle timestamp, updated only after the manifest and every
+selected resource have been checked successfully. A partial failure preserves
+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. 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.
+
+During initial installation, selected resources are cached before the browser
+activates the worker. Failures remain observable through native worker state
+and SDK diagnostics. HTTP modification dates have second-level precision;
+hosts must report changes to the served representation, including generated
+output, rather than only the date of an unrelated source file.
 
 The SDK development server sends `Cache-Control: no-cache` for PWA resources.
-An independent static host must also revalidate stable HTML, module, style,
-import-map and worker URLs, and serve JavaScript with a JavaScript content type.
+An independent static host should support `Last-Modified` and conditional GET
+for stable HTML, module, style and import-map URLs, revalidate worker URLs, and
+serve JavaScript with a JavaScript content type.
 Keep the worker beside the deployment root it controls. The browser requires a
 supported secure context, such as trusted HTTPS or localhost, to register it.
 The SDK does not change certificates or browser permissions.
@@ -132,14 +209,165 @@ worker while they are open. Closing those pages allows activation; a refresh
 can leave overlapping document clients and keep the update waiting.
 
 The SDK does not call `skipWaiting`, claim the initial page, reload a page,
-restart a model or poll for updates. Activation retires only obsolete resource
-caches belonging to that exact app and registration scope. Saved application
-data and caches owned by other capabilities are untouched.
+restart a model or poll for updates. Worker activation preserves cached
+resources and the DBOPFS check history for the same app and registration scope.
+Saved application data and caches owned by other capabilities are untouched.
+
+When importing caches from an older SDK worker, the new worker fetches the
+SDK-owned registration bootstrap and PWA client once so the page can use the
+current cache-check protocol. Other cached resource bodies retain the normal
+check cadence. This transition follows native worker installation and
+activation without forcing a page reload.
 
 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