arcane-os 0.11.3 → 0.13.0

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 |
@@ -3459,6 +3462,15 @@ async function useselectApp(...arguments_) {
 
 Starts one owned browser development server with exact runtime/app route mappings and a caller-selected bind address.
 
+HTTPS serving uses the published `node-http-server` module. The SDK
+selects source routes and supplies generated representations; the module owns
+static-file conditional GET/HEAD handling and response delivery. The SDK
+retains modification dates for its generated representations. Unchanged
+resources can return `304` with no body while changed resources return their
+complete current representation. PEM-path listeners use module deployment;
+explicit raw `tls` options retain native HTTPS transport with the same module
+response and static-file operations.
+
 ### Signature, modes, and result
 
 ```text
@@ -3466,53 +3478,64 @@ async startDevServer(options={})
 ```
 
 Import it from `arcane-os`. Source mode accepts
-`{workspaceRoot=process.cwd(), appId, mode='source', host='127.0.0.1', port=0,
-https=false, certPath, keyPath, tls, signal, onEvent}` and serves one validated
+`{workspaceRoot=process.cwd(), appId, mode='source', host='127.0.0.1', port=0, httpPort=0,
+certPath, keyPath, tls, signal, onEvent}` and serves one validated
 workspace application plus its complete SDK or integrated runtime. Packaged mode uses
-`{mode:'packaged', releaseRoot, host, port, signal, onEvent}` and serves the
-complete selected release files. `host` defaults to `127.0.0.1` and accepts an
+`{mode:'packaged', releaseRoot, workspaceRoot, host, port, httpPort, certPath, keyPath, tls,
+signal, onEvent}` and serves the complete selected release files.
+`host` defaults to `127.0.0.1` and accepts an
 explicit network address or hostname. Use `0.0.0.0` for all IPv4 interfaces or
-`::` for the platform's IPv6 wildcard listener; port `0` asks the operating
-system for an available port.
-
-`https:true` reads `.arcane/dev/server-cert.pem` and
+`::` for the platform's IPv6 wildcard listeners. `port` selects the HTTPS
+application port, and `httpPort` selects the paired HTTP redirect port. Each
+defaults to `0`, which asks the operating system for an available port.
+The SDK request hook returns `308` for HTTP with a `Location` pointing to the
+actual HTTPS port while preserving the original request path and query. Both listeners
+use the selected host.
+
+Every source server and packaged browser preview enforces HTTPS, including
+localhost. The legacy `https` option is accepted but cannot disable it.
+Startup reads `.arcane/dev/server-cert.pem` and
 `.arcane/dev/server-key.pem` relative to `workspaceRoot` unless explicit
-`certPath` and `keyPath` are supplied together. The path pair also selects
-HTTPS without `https:true`; relative paths resolve from the workspace. A
-direct `tls` object instead supplies Node HTTPS server options, including
+`certPath` and `keyPath` are supplied together; relative paths resolve from the
+workspace. A direct `tls` object instead supplies Node HTTPS server options, including
 `cert` and `key`, without reading certificate files. Keep private material
 server-side. Missing PEM files and Node certificate/key parse errors reject
 startup without falling back to HTTP. Node owns TLS option handling and the
 handshake; browser trust and address matching are evaluated when a client
-connects. The CLI's `--public` selects HTTPS and the wildcard bind;
+connects. The CLI's `--public` selects the wildcard bind;
 the API's `host` option alone changes only the bind address.
 
-The promise settles after the listener is ready and resolves to
+The promise settles after both listeners are ready and resolves to
 `{server, protocol, mode, workspaceRoot, appId, host, port, origin, cleanUrl, url,
-networkUrls, close, closed, lifecycle}`. `server` is the raw Node HTTP or HTTPS
-server; `protocol` is `'http:'` or `'https:'`.
+networkUrls, httpPort, httpOrigin, httpUrl, close, closed, lifecycle}`. `server` is the raw Node HTTPS
+server; `protocol` is `'https:'`.
 `url` and `cleanUrl` are the same application URL. Wildcard listeners use
 `localhost` in that local URL; `host` retains the actual bound address.
+`httpPort` is the actual HTTP listener port, `httpOrigin` is its HTTP origin,
+and `httpUrl` combines that origin with the application start path. These
+fields identify the redirect endpoint; `origin`, `url`, `cleanUrl`, and
+`networkUrls` identify HTTPS application endpoints.
 `networkUrls` lists application URLs for applicable non-loopback interface
 addresses discovered once at startup. These URLs are connection candidates,
 not evidence of reachability from another device. The server adds no session
 capability or authentication. In packaged mode, `workspaceRoot` and `appId`
 are `null`.
 
-All returned application URLs use the selected transport's scheme. The server
-reads one PEM pair per startup and does not create certificates or modify trust
-stores. Each client must trust the issuing CA and open an address covered by the
+PEM-path startup reads the selected pair. The server does not create
+certificates or modify trust stores. Each client must trust the issuing CA and open an address covered by the
 server certificate. Lifecycle events and CLI summaries exclude TLS options and
 private key contents. See [development HTTPS setup](cli.md#development-https-setup).
 
-Starting the server opens the selected listener and emits awaited,
-backpressured `server.starting` and `server.started` events. Request failures
-emit `server.request.failed`; shutdown emits `server.stopped` after owned
+Starting the server opens both selected listeners and emits awaited,
+backpressured `server.starting` and `server.started` events. `server.started`
+includes `httpPort`, `httpOrigin`, and `httpUrl` alongside the HTTPS endpoint.
+Request failures emit `server.request.failed`; shutdown emits `server.stopped` after owned
 requests and event delivery drain. Call `await result.close()` in a `finally`
 block, or abort `signal`; `close()` is idempotent and returns the
-same settlement represented by both `closed` and `lifecycle`. A listener error
-or event-callback failure closes the server and rejects its lifecycle. Invalid
-mode/host/port, malformed workspace or release content, an occupied port,
+same settlement represented by both `closed` and `lifecycle`. Closing the
+operation closes both listeners. An error from either listener or an
+event-callback failure closes both and rejects the lifecycle. Invalid
+mode/host/port/httpPort, malformed workspace or release content, an occupied port,
 or an already-aborted signal rejects startup.
 
 ### Availability and normalization
@@ -3907,9 +3930,16 @@ async function usedescribeTargets(...arguments_) {
 Starts one owned browser development server for the selected application.
 
 `https`, `certPath`, `keyPath`, and `tls` follow the
-[`startDevServer()` TLS contract](#startdevserver), alongside `host` and `port`.
-The operation refreshes the selected app's managed import maps once, then owns
-one source listener and returns its protocol, URLs, and shutdown lifecycle.
+[`startDevServer()` TLS contract](#startdevserver), alongside `host`, `port`, and
+`httpPort`. `port` selects HTTPS and `httpPort` selects the HTTP `308` redirect
+listener; each defaults to an available port.
+The operation refreshes the selected authored descriptor's `arcane-package.json`
+projection and managed import maps under one development-refresh lock, then
+releases that lock before opening the HTTPS source listener and its HTTP
+redirect listener. It returns both endpoints and their shared shutdown
+lifecycle. Legacy package-only apps remain unchanged. The operation generates
+no packaged output; enabled PWA manifests
+are served directly from the selected source resources.
 
 ### Signature and result
 
@@ -6075,6 +6105,13 @@ registration and returns a synchronous owner with `ready`, `state`, `subscribe`,
 `update` and `dispose`. It does not block page rendering or load models.
 Unsupported environments receive an explicit unsupported state.
 
+The generated page bootstrap also starts the SDK's background resource check.
+It stores one `lastChecked` timestamp per app/cache in DBOPFS, advancing it only
+after the full resource check succeeds, and revalidates on page load after
+120 seconds in development or 15 minutes in packaged delivery. Complete
+responses remain cached without SDK expiration; `304` retains the response
+and a successful replacement updates it. See the [PWA guide](pwa.md).
+
 ### Example
 
 ```javascript
@@ -6090,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.11.3",
+  "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",
@@ -105,6 +105,7 @@
   },
   "dependencies": {
     "event-pubsub": "6.1.0",
+    "node-http-server": "9.1.1",
     "strong-type": "2.0.1",
     "vanilla-test": "2.1.3"
   },

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/app-descriptor.mjs

@@ -1,7 +1,8 @@
 import Is from 'strong-type';
 import {isDeepStrictEqual} from 'node:util';
-import {readFile} from 'node:fs/promises';
+import {readFile, writeFile} from 'node:fs/promises';
 import path from 'node:path';
+import {throwIfAborted} from './errors.mjs';
 import {normalizePwaConfig} from './pwa.mjs';
 import {
     ARCANE_MACHINE_BUNDLE_VERSION,
@@ -424,6 +425,47 @@ async function readJsonFile(filePath,label,{optional=false}={}){
     }
 }
 
+export async function refreshAppPackageProjection({workspaceRoot, appId, signal, onEvent}) {
+    throwIfAborted(signal);
+    const appRoot = path.join(workspaceRoot, 'apps', appId);
+    const descriptorPath = path.join(appRoot, APP_DESCRIPTOR_NAME);
+    const authored = await readJsonFile(
+        descriptorPath,
+        `apps/${appId}/${APP_DESCRIPTOR_NAME}`,
+        {optional: true}
+    );
+    if (authored === null) return {updated: false};
+
+    validateAppDescriptor(
+        authored,
+        {appId}
+    );
+    const projection = projectPackageManifest(authored);
+    const packagePath = path.join(appRoot, 'arcane-package.json');
+    const packageManifest = await readJsonFile(
+        packagePath,
+        `apps/${appId}/arcane-package.json`
+    );
+    const packageProjection = packageManifest.pwa === undefined ? packageManifest : {
+        ...packageManifest,
+        pwa: normalizePwaConfig(packageManifest.pwa)
+    };
+    if (isDeepStrictEqual(projection, packageProjection)) return {updated: false};
+
+    // Development updates the generated projection before strict workspace readers run.
+    throwIfAborted(signal);
+    await writeFile(packagePath, `${JSON.stringify(projection, null, 2)}\n`, 'utf8');
+    await onEvent?.(
+        {
+            type: 'workspace.application.projection.updated',
+            workspaceRoot,
+            appId,
+            path: packagePath
+        }
+    );
+    return {updated: true};
+}
+
 export async function loadAppDescriptor({workspaceRoot,appRoot,appId,packageManifest}){
     const descriptorPath=path.join(appRoot,APP_DESCRIPTOR_NAME);
     const authored=await readJsonFile(descriptorPath,`apps/${appId}/${APP_DESCRIPTOR_NAME}`,{optional:true});