arcane-os 0.12.0 → 0.13.1

package/docs/reference/runtime-components.md

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

package/docs/reference/sdk-api.md

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

package/package.json

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

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

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