arcane-os 0.8.1 → 0.10.0

package/docs/reference/sdk-api.md

@@ -2,9 +2,9 @@
 
 The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`,
-`arcane-os/preference-store`, `arcane-os/speech-playback`, and
-`arcane-os/speech-text` entrypoints, and the browser-only
-`arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
+`arcane-os/preference-store`, `arcane-os/speech-playback`,
+`arcane-os/speech-text`, and `arcane-os/browser-device` entrypoints, and the browser-only
+`arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
 Those package subpaths are distinct from application-facing projection modules
 in the managed browser map, such as `arcane/AIProviderRuntime`,
 `arcane/AIRuntimeState`, and `arcane/ThemeBootstrap`. Applications use those
@@ -38,6 +38,8 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
 | `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/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. |
@@ -124,6 +126,9 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `createBrowserWhisperProvider()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser with Workers, object URLs, caller-selected Whisper runtime/model artifacts, and an SDK DBOPFS speech store |
 | `createCanonicalUstarHeader()` | function | `arcane-os` | Packaging and release bundles | Node |
 | `createDbopfsModelStore()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser with a ready DBOPFS instance and OPFS |
+| `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 |
 | `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 |
@@ -6007,6 +6012,84 @@ const source = createBrowserModelSource({
 });
 ```
 
+## getBrowserDeviceClass()
+
+### Overview
+
+Returns `mobile` or `desktop` to select application-owned settings. Phones and
+tablets use `mobile` when browser client hints, platform, user-agent information,
+or the iPadOS Mac-platform/touch combination identifies them. Missing or
+unrecognized identity uses `desktop`.
+
+### Signature and result
+
+```text
+getBrowserDeviceClass(navigatorObject = globalThis.navigator)
+```
+
+The optional navigator-like object supplies `userAgentData`, `userAgent`,
+`platform`, and `maxTouchPoints`. The synchronous string result reports a
+settings class, not hardware capability or readiness.
+
+### Availability and normalization
+
+Import from `arcane-os/browser-device` in Node or a browser. The dependency-free
+entrypoint reads only the supplied or global browser identity and does not load
+an AI runtime. No model, GPU, storage, network, or listener operation runs.
+Missing or unrecognized identity returns `desktop`; browser identity masking
+can affect classification. Existing provider defaults remain unchanged unless
+the caller selects and supplies its own profile.
+
+### Example
+
+```javascript
+import {getBrowserDeviceClass} from 'arcane-os/browser-device';
+
+const deviceClass = getBrowserDeviceClass();
+console.log(deviceClass); // mobile or desktop
+```
+
+## PWA_STATE_EVENT
+
+### Overview
+
+The event name `arcane.pwa.state` identifies PWA registration and native worker
+lifecycle state published through the existing Arcane event owner.
+
+### Example
+
+```javascript
+import {PWA_STATE_EVENT} from 'arcane-os/pwa';
+console.log(PWA_STATE_EVENT);
+```
+
+See the [PWA state contract](pwa.md#registerpwa) for complete payload fields and
+current-state subscriptions. Importing the constant does not register a worker.
+
+## registerPwa()
+
+### Overview
+
+`registerPwa({workerUrl = './arcane-sw.js', scope} = {})` starts native browser
+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.
+
+### Example
+
+```javascript
+import {registerPwa} from 'arcane-os/pwa';
+const pwa = registerPwa();
+pwa.ready.catch(function reportRegistrationError(error) {
+    console.error(error);
+});
+```
+
+The [PWA guide](pwa.md) defines inputs, native registration results, error state,
+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.
+
 ## createBrowserWasmLlmProvider()
 
 ### Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -14,6 +14,8 @@
     "./events": "./src/events.mjs",
     "./event-manager": "./src/event-manager.mjs",
     "./logging": "./browser-runtime/logging.mjs",
+    "./browser-device": "./browser-runtime/browser-device.mjs",
+    "./pwa": "./browser-runtime/pwa.mjs",
     "./preference-store": "./runtime/arcane/modules/PreferenceStore.js",
     "./speech-playback": "./runtime/arcane/modules/SpeechPlayback.js",
     "./speech-text": "./browser-runtime/speech-text.mjs",
@@ -65,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/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/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-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/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/modules/HTMLImport.js

@@ -19,8 +19,13 @@ let htmlImportScriptId=0;
 const htmlImportModuleURL=new URL(import.meta.url);
 const htmlImportAssetVersion=htmlImportModuleURL.searchParams.get('arcaneVersion');
 
+function pwaResourceUrlsEnabled(){
+  return Boolean(document.querySelector?.('script[data-arcane-pwa]'));
+}
+
 function versionComponentResource(value,baseHref){
-  if(!htmlImportAssetVersion||!is.string(value)||!value||value.startsWith('#')){
+  const clean=pwaResourceUrlsEnabled();
+  if((!htmlImportAssetVersion&&!clean)||!is.string(value)||!value||value.startsWith('#')){
     return value;
   }
   let resolvedURL;
@@ -46,7 +51,7 @@ function versionComponentResource(value,baseHref){
     const parameter=new URLSearchParams(field);
     if(parameter.has('v'))return null;
     if(!parameter.has('arcaneVersion'))return field;
-    if(replaced)return null;
+    if(clean||replaced)return null;
     replaced=true;
     const equals=field.indexOf('=');
     const key=equals<0?field:field.slice(0,equals);
@@ -54,6 +59,11 @@ function versionComponentResource(value,baseHref){
   }).filter(function retainQueryField(field){
     return field!==null;
   }):[];
+  if(clean){
+    return fields.some(function hasRemainingField(field){return field!=='';})
+      ?`${pathname}?${fields.join('&')}${fragment}`
+      :`${pathname}${fragment}`;
+  }
   if(!replaced){
     if(fields.at(-1)==='')fields[fields.length-1]=versionField;
     else fields.push(versionField);
@@ -81,7 +91,7 @@ function resolveComponentResource(value,runtimeRoot){
 }
 
 function resolveComponentStyleResources(styleText,runtimeRoot){
-  if(!runtimeRoot&&!htmlImportAssetVersion)return styleText;
+  if(!runtimeRoot&&!htmlImportAssetVersion&&!pwaResourceUrlsEnabled())return styleText;
   const parts=[];
   let copiedThrough=0;
   let index=0;

package/schemas/arcane-app.schema.json

@@ -40,6 +40,7 @@
         "entry": { "$ref": "#/$defs/relativePath" },
         "strategy": { "enum": ["static", "adapter"] },
         "localAIModelPolicy": { "$ref": "#/$defs/localAIModelPolicy" },
+        "pwa": { "$ref": "#/$defs/pwa" },
         "include": { "$ref": "#/$defs/nonemptyPathList" },
         "exclude": { "$ref": "#/$defs/pathList" },
         "shared": {
@@ -224,6 +225,33 @@
     }
   ],
   "$defs": {
+    "pwa": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "manifest": {
+          "type": "object",
+          "description": "Application-owned Web App Manifest members, including branding, icons, and presentation."
+        },
+        "offline": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "include": {
+              "type": "array",
+              "description": "Literal package paths or directories to cache. Omitted or empty selects all emitted files.",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "exclude": {
+              "type": "array",
+              "description": "Literal package paths or directories excluded from offline assets. Generated shell records and the entry remain available.",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
     "appId": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
     "presentationText": {
       "type": "string",

package/schemas/arcane-package.schema.json

@@ -43,6 +43,9 @@
     "localAIModelPolicy": {
       "$ref": "#/$defs/localAIModelPolicy"
     },
+    "pwa": {
+      "$ref": "#/$defs/pwa"
+    },
     "security": {
       "type": "object",
       "additionalProperties": false,
@@ -117,6 +120,33 @@
     }
   ],
   "$defs": {
+    "pwa": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "manifest": {
+          "type": "object",
+          "description": "Application-owned Web App Manifest members, including branding, icons, and presentation."
+        },
+        "offline": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "include": {
+              "type": "array",
+              "description": "Literal package paths or directories to cache. Omitted or empty selects all emitted files.",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "exclude": {
+              "type": "array",
+              "description": "Literal package paths or directories excluded from offline assets. Generated shell records and the entry remain available.",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
     "appId": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"

package/src/app-descriptor.mjs

@@ -2,6 +2,7 @@ import Is from 'strong-type';
 import {isDeepStrictEqual} from 'node:util';
 import {readFile} from 'node:fs/promises';
 import path from 'node:path';
+import {normalizePwaConfig} from './pwa.mjs';
 import {
     ARCANE_MACHINE_BUNDLE_VERSION,
     ARCANE_PROTOCOL,
@@ -107,7 +108,7 @@ function validateLocalAIModelPolicy(value,label){
 
 function validatePackage(value,appId){
     assertOnlyKeys(value,new Set([
-        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy'
+        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa'
     ]),'descriptor.package');
     const entry=normalizeRelativePath(value.entry,'descriptor.package.entry');
     if(!['static','adapter'].includes(value.strategy))fail('descriptor.package.strategy must be static or adapter.');
@@ -135,6 +136,7 @@ function validatePackage(value,appId){
         include,
         exclude,
         shared,
+        ...(value.pwa===undefined?{}:{pwa:normalizePwaConfig(value.pwa)}),
         ...(adapter?{adapter}:{}),
         ...(value.localAIModelPolicy===undefined?{}:{
             localAIModelPolicy:validateLocalAIModelPolicy(
@@ -320,6 +322,7 @@ export function projectPackageManifest(descriptor){
             mediaOrigins:[...value.security.mediaOrigins]
         }}:{}),
         ...(value.package.localAIModelPolicy?{localAIModelPolicy:value.package.localAIModelPolicy}:{}),
+        ...(value.package.pwa===undefined?{}:{pwa:value.package.pwa}),
         include:[...value.package.include],
         exclude:[...value.package.exclude],
         shared:[...value.package.shared],
@@ -378,6 +381,7 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             entry:packageManifest.entry,
             strategy:packageManifest.strategy,
             ...(packageManifest.localAIModelPolicy?{localAIModelPolicy:packageManifest.localAIModelPolicy}:{}),
+            ...(packageManifest.pwa===undefined?{}:{pwa:packageManifest.pwa}),
             include:[...packageManifest.include],
             exclude:[...(packageManifest.exclude??[])],
             shared:[...packageManifest.shared],
@@ -426,7 +430,11 @@ export async function loadAppDescriptor({workspaceRoot,appRoot,appId,packageMani
     if(authored){
         const descriptor=validateAppDescriptor(authored,{appId});
         const projection=projectPackageManifest(authored);
-        if(!isDeepStrictEqual(projection,packageManifest)){
+        const packageProjection=packageManifest.pwa===undefined?packageManifest:{
+            ...packageManifest,
+            pwa:normalizePwaConfig(packageManifest.pwa)
+        };
+        if(!isDeepStrictEqual(projection,packageProjection)){
             fail(`${APP_DESCRIPTOR_NAME} does not project exactly to arcane-package.json.`);
         }
         return completeValue({descriptor,source:'authored',descriptorPath});