arcane-os 0.16.1 → 0.16.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.16.3
+
+- Remember browser-reported PWA installation in app-scoped DBOPFS and suppress
+  the SDK's floating and inline installation controls on later visits. Capture
+  native events immediately while restoring the saved flag; keep rendering,
+  component loading and worker registration independent.
+- Preserve confirmed installation across late reads, prompt results and display
+  changes. Save installed-app launches as well as `appinstalled`, without
+  mistaking prompt acceptance or ordinary fullscreen for installation. Expose
+  initial storage readiness and complete persistence errors through the shared
+  install owner, and retain confirmed-install writes through owner disposal.
+
+## 0.16.2
+
+- Scope explicit application selection and workspace resolution to the named
+  app before reading its descriptor. An unrelated invalid descriptor no longer
+  blocks that operation. Selected descriptors and unscoped discovery retain
+  their existing validation. Named resolution reports only the selected app in
+  `appIds`; unknown selections report the requested missing identifier without
+  validating or listing unrelated apps.
+
 ## 0.16.1
 
 - Remove raw script elements and inline event-handler attributes at the

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.16.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.16.2` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/browser-runtime/pwa-install.mjs

@@ -11,7 +11,11 @@ export function getPwaInstall() {
     if (sharedOwner && sharedOwner.state.status !== 'disposed') {
         return sharedOwner;
     }
-    const owner = {get state() { return snapshot(); }, subscribe, prompt, dismiss, dispose};
+    const owner = {
+        get state() { return snapshot(); },
+        get ready() { return ready; },
+        subscribe, prompt, dismiss, dispose
+    };
     const source = createArcaneEventSource(owner, {
         source: 'arcane.pwa.install', eventTypes: [PWA_INSTALL_STATE_EVENT]
     });
@@ -20,6 +24,9 @@ export function getPwaInstall() {
         '(display-mode: standalone), (display-mode: minimal-ui), '
         + '(display-mode: fullscreen), (display-mode: window-controls-overlay)'
     );
+    const installedDisplayMode = globalThis.matchMedia?.(
+        '(display-mode: standalone), (display-mode: minimal-ui), (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;
@@ -28,6 +35,11 @@ export function getPwaInstall() {
     let status = isRunningAsApp() ? 'running' : 'waiting';
     let outcome = null;
     let error = null;
+    let installed = isInstalledApp();
+    let storedInstalled = false;
+    let storageReady = false;
+    let storageError = null;
+    let saveTask = null;
     try {
         dismissed = globalThis.sessionStorage?.getItem(dismissalKey) === 'true';
     } catch (storageError) {
@@ -38,9 +50,17 @@ export function getPwaInstall() {
         return displayMode?.matches === true || globalThis.navigator?.standalone === true;
     }
 
+    function isInstalledApp() {
+        // Ordinary browser fullscreen is not evidence of installation.
+        return installedDisplayMode?.matches === true || globalThis.navigator?.standalone === true;
+    }
+
     function snapshot() {
-        return {status, available: deferredPrompt !== null && !disposed,
-            dismissed, outcome, error};
+        return {
+            status,
+            available: storageReady && deferredPrompt !== null && !installed && !isRunningAsApp() && !disposed,
+            installed, dismissed, outcome, error, storageError
+        };
     }
 
     function publish(nextStatus, nextError = null) {
@@ -67,24 +87,92 @@ export function getPwaInstall() {
         }
     }
 
+    async function loadInstallStorage() {
+        if (!globalThis.dbopfs) {
+            await import('arcane/DBOPFS');
+        }
+        const storage = globalThis.dbopfs;
+        if (!storage) {
+            throw new Error('PWA installation state could not open DBOPFS.');
+        }
+        await storage.readyPromise;
+        return storage;
+    }
+
+    function reportStorageError(failure) {
+        storageError = failure;
+        console.warn('Arcane PWA installation state could not be persisted or restored:', failure);
+        publish(status, error);
+    }
+
+    async function restoreInstallation() {
+        try {
+            const storage = await storageTask;
+            const record = await storage.get('pwa', 'installed.json', true);
+            storedInstalled = record?.installed === true;
+            if (!disposed && storedInstalled) {
+                installed = true;
+                deferredPrompt = null;
+            }
+        } catch (failure) {
+            reportStorageError(failure);
+        }
+        storageReady = true;
+        if (!disposed) {
+            if (installed) {
+                publish(isRunningAsApp() ? 'running' : 'installed', error);
+            } else if (deferredPrompt && !isRunningAsApp()) {
+                publish('available', error);
+            } else {
+                publish(status, error);
+            }
+        }
+        return snapshot();
+    }
+
+    async function saveInstallation() {
+        // The initial read avoids rewriting an already remembered installation.
+        await ready;
+        if (storedInstalled) return;
+        const storage = await storageTask;
+        await storage.set(
+            'pwa',
+            'installed.json',
+            {installed: true}
+        );
+        storedInstalled = true;
+        storageError = null;
+        publish(status, error);
+    }
+
+    function rememberInstallation() {
+        installed = true;
+        deferredPrompt = null;
+        // Retain and observe this durable write even if the page owner detaches.
+        saveTask ??= saveInstallation().catch(reportStorageError);
+    }
+
     function onBeforeInstallPrompt(event) {
-        if (disposed || isRunningAsApp() || status === 'installed' || status === 'accepted') return;
+        if (disposed || installed || isRunningAsApp() || status === 'accepted') return;
         event.preventDefault();
         deferredPrompt = event;
         outcome = null;
-        publish('available');
+        publish(storageReady ? 'available' : 'waiting');
     }
 
     function onInstalled() {
-        deferredPrompt = null;
+        rememberInstallation();
         // This event may precede Android's completion of WebAPK creation.
         publish('installed');
     }
 
     function onDisplayModeChange() {
+        if (isInstalledApp()) rememberInstallation();
         if (isRunningAsApp()) {
             deferredPrompt = null;
             publish('running');
+        } else if (installed) {
+            publish('installed');
         } else if (status === 'running') {
             publish('waiting');
         }
@@ -108,7 +196,7 @@ export function getPwaInstall() {
     }
 
     function prompt() {
-        if (disposed || !deferredPrompt) return Promise.resolve(null);
+        if (!snapshot().available) return Promise.resolve(null);
         const event = deferredPrompt;
         deferredPrompt = null;
         publish('prompting');
@@ -162,8 +250,12 @@ export function getPwaInstall() {
     observe(globalThis, 'beforeinstallprompt', onBeforeInstallPrompt);
     observe(globalThis, 'appinstalled', onInstalled);
     observe(displayMode, 'change', onDisplayModeChange);
+    observe(installedDisplayMode, 'change', onDisplayModeChange);
     observe(globalThis, 'pagehide', onPageHide);
     sharedOwner = owner;
+    const storageTask = loadInstallStorage();
+    const ready = restoreInstallation();
+    if (installed) rememberInstallation();
     return owner;
 }
 

package/docs/reference/pwa.md

@@ -293,18 +293,29 @@ does not infer installation support from the user-agent string. See
 ## getPwaInstall()
 
 Import `getPwaInstall` and `PWA_INSTALL_STATE_EVENT` from `arcane-os/pwa`.
-`getPwaInstall()` synchronously returns the shared page owner with `state`,
+`getPwaInstall()` synchronously returns the shared page owner with `state`, `ready`,
 `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`.
+`state` contains `status`, `available`, `installed`, `dismissed`, `outcome`,
+`error` and `storageError`.
 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`.
+is retained, the initial installation-record read has settled, and installation
+has not been recorded or detected. A dismissed floating suggestion can still
+have `available: true`. `installed` is true after browser-reported installation
+or restoration of that app's saved installation record.
 `outcome` is the browser's `accepted` or `dismissed` choice, or `null` before a
-choice. `error` carries the complete prompt error, or `null`.
+choice. `error` carries the complete prompt error, or `null`; `storageError`
+carries the complete DBOPFS read or write error, or `null`.
+
+`ready` resolves to the state after the initial DBOPFS read settles. Native
+events are captured synchronously while this read runs. Only installation
+availability waits for it; page rendering, component loading and worker
+registration continue independently. A storage failure is logged and published
+as `storageError`; `ready` still resolves and native installation remains usable.
 
 `subscribe(listener, {emitCurrent: true, signal} = {})` immediately replays
 state by default and returns an unsubscribe function. Later state travels
@@ -315,7 +326,8 @@ 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
+when installation is unavailable, including while the saved state is loading
+or after installation is remembered. Failure publishes
 `error` state and rejects. A new native event is required for another prompt.
 
 ```javascript
@@ -336,8 +348,24 @@ installButton.addEventListener('click', function requestInstallation() {
 
 `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
+too. `appinstalled` clears the event, publishes `installed`, and saves
+`{installed: true}` as `pwa/installed.json` through the current app-scoped
+DBOPFS singleton. An installed-app launch in standalone, minimal-ui or
+window-controls-overlay mode, or with `navigator.standalone === true`, also
+records installation. Ordinary fullscreen suppresses the current prompt but
+does not record installation because browsers can enter fullscreen without
+installing an app; see the [display-mode specification](https://drafts.csswg.org/mediaqueries-5/#display-modes).
+
+Every new owner reads the saved flag, so both floating and explicit inline
+controls stay hidden on subsequent visits in that browser origin's app scope.
+The SDK never clears this flag or resets it when display mode changes. Prompt
+acceptance and dismissal alone do not write it. The record is independent of
+resource-check history and other application data. A pending read cannot undo
+newly observed installation, and a confirmed installation's pending write is
+retained through owner disposal. A write failure remains observable without
+making the current installed session eligible again.
+
+Running in an app display mode publishes `running`. 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/).

package/docs/reference/runtime-components.md

@@ -1069,6 +1069,12 @@ 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.
+The shared SDK owner persists browser-reported installation in app-scoped
+DBOPFS. Both floating and inline controls stay hidden while that record is
+loading and remain hidden on later visits when installation is remembered.
+Acceptance alone does not save installation. The component's `ready` means
+its methods and subscription are attached; storage completion belongs to the
+shared owner's `ready` promise and does not delay page rendering.
 
 ### Example
 

package/docs/reference/sdk-api.md

@@ -6231,13 +6231,24 @@ payload and current-state subscription behavior.
 
 ### Overview
 
-`getPwaInstall()` returns one synchronous page owner exposing `state`,
+`getPwaInstall()` returns one synchronous page owner exposing `state`, `ready`,
 `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`.
+State contains `status`, `available`, `installed`, `dismissed`, `outcome`,
+`error` and `storageError`. The owner restores `pwa/installed.json` through the
+app-scoped DBOPFS singleton and saves `{installed: true}` after `appinstalled`
+or an installed-app launch. Remembered installation suppresses both floating
+and inline controls on later visits. Acceptance alone and ordinary fullscreen
+do not record installation.
+
+`ready` resolves to the state once the initial read settles. Native events are
+captured immediately, while install availability waits for that read. Rendering
+and worker registration remain independent. Storage failures are logged and
+published in `storageError`; they do not reject `ready` or reverse an observed
+installation. Confirmed-install writes remain owned after disposal.
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "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 @@
   "scripts": {
     "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:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.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-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",

package/src/workspace.mjs

@@ -216,12 +216,17 @@ function classifyRootConfig(config){
     });
 }
 
-async function discoverAppsInRoot(root,config){
+async function discoverAppsInRoot(root,config,appId){
+    if(appId!==undefined&&(!is.string(appId)||!APP_ID_PATTERN.test(appId))){
+        fail(`Invalid app id: ${String(appId)}.`,'ARCANE_USAGE');
+    }
     const appsRoot=path.join(root,'apps');
     await assertRealDirectory(appsRoot,'Workspace apps root');
     const entries=await readdir(appsRoot,{withFileTypes:true});
     const apps=[];
     for(const entry of entries.sort((left,right)=>ordinal(left.name,right.name))){
+        // A named operation validates that app, not unrelated application descriptors.
+        if(appId!==undefined&&entry.name!==appId)continue;
         if(!APP_ID_PATTERN.test(entry.name))continue;
         if(entry.isSymbolicLink())fail(`apps/${entry.name} must not be a symbolic link or junction.`);
         if(!entry.isDirectory())continue;
@@ -274,13 +279,11 @@ export async function inspectWorkspaceProfile(workspaceRoot=process.cwd()){
 }
 
 export async function selectApp(workspaceRoot=process.cwd(),appId){
-    const apps=await discoverApps(workspaceRoot);
-    if(appId!==undefined&&(!is.string(appId)||!APP_ID_PATTERN.test(appId))){
-        fail(`Invalid app id: ${String(appId)}.`,'ARCANE_USAGE');
-    }
+    const profile=await inspectWorkspaceProfile(workspaceRoot);
+    const apps=await discoverAppsInRoot(profile.workspaceRoot,profile.config,appId);
     if(appId){
         const selected=apps.find(app=>app.appId===appId);
-        if(!selected)fail(`Unknown app "${appId}". Available apps: ${apps.map(app=>app.appId).join(', ')||'[none]'}.`);
+        if(!selected)fail(`Unknown app "${appId}".`);
         return selected;
     }
     if(apps.length===0)fail('No Arcane applications were found under apps/.');
@@ -294,14 +297,11 @@ export async function resolveWorkspace({workspaceRoot=process.cwd(),appId}={}){
     const profile=await inspectWorkspaceProfile(workspaceRoot);
     const canonicalRoot=profile.workspaceRoot;
     const config=profile.config;
-    const apps=await discoverAppsInRoot(canonicalRoot,config);
-    if(appId!==undefined&&(!is.string(appId)||!APP_ID_PATTERN.test(appId))){
-        fail(`Invalid app id: ${String(appId)}.`,'ARCANE_USAGE');
-    }
+    const apps=await discoverAppsInRoot(canonicalRoot,config,appId);
     let app;
     if(appId){
         app=apps.find(item=>item.appId===appId);
-        if(!app)fail(`Unknown app "${appId}". Available apps: ${apps.map(item=>item.appId).join(', ')||'[none]'}.`);
+        if(!app)fail(`Unknown app "${appId}".`);
     }else if(apps.length===1){
         [app]=apps;
     }else if(apps.length===0){