arcane-os 0.71.2 → 0.73.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.73.0
+
+- Add public `resolvePwaRetirementResponse({workspaceRoot, appId})` for existing
+  custom Node hosts. It supplies the shared retirement worker response only for
+  an explicitly disabled standalone PWA whose authored root worker is absent.
+- Preserve raw `enabled: false` selection before descriptor normalization in
+  custom-host and SDK source serving. Omitted settings, enabled PWAs, authored
+  workers and other routes keep their existing behavior.
+- Retire only the worker's own registration through the existing browser
+  lifecycle. Saved data, caches, DBOPFS and open pages remain untouched; no
+  forced reload, polling or replacement server is introduced.
+
+## 0.72.0
+
+- Add optional `native.launchContext` defaults for ordinary packaged launch and
+  public `resolveNativeLaunchContext()` through `arcane-os/core/host`. Native
+  applications and external MCP can select the same app-owned state, workspace,
+  shared endpoint and log without reconstructing platform paths.
+- Extend `readCoreLaunchContext()` with explicit defaults and opt-in native
+  resolution. Preserve complete explicit launch records, selected workspace
+  values, ordinary stdio ownership and the existing no-option entry path.
+- Forward packaged launch defaults through Windows and macOS launchers while
+  preserving window, profile, service and shared-host lifecycle behavior. No
+  stored-data migration or dependency change is introduced.
+
 ## 0.71.2
 
 - Preserve complete browser Kokoro synthesis input through the selected runtime's

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.71.2` SDK contract. Development applications declare
+This checkout defines the `0.73.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/docs/reference/README.md

@@ -43,6 +43,7 @@ alone does not make bare module names resolve in a browser.
 | Use the `arcane` command | [CLI reference](cli.md) |
 | Install an app and cache selected resources offline | [Progressive web applications](pwa.md) |
 | Disable source PWA generation or explicitly retire confirmed generated output | [Source PWA retirement](pwa.md#disable-source-pwa-generation-and-retire-generated-output) |
+| Retire the prior worker after explicitly disabling standalone source PWA | [Disabled-worker browser lifecycle](pwa.md#disabled-worker-retirement-on-the-source-server) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Connect an application through the shared WebSocket transport | [Shared WebSocket clients](websocket-client.md) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
@@ -53,7 +54,7 @@ alone does not make bare module names resolve in a browser.
 | Choose theme-switcher corner radii, label font and group background through host CSS | [Theme-switcher styling properties](runtime-components.md#theme-switcherhtml) |
 | Use optional Core preferences and appearance without masking real failures | [PreferenceStore](runtime-modules.md#preferencestorejs), [SystemAppearance](runtime-modules.md#systemappearancejs), and [Core lookup errors](core-runtime.md#state-and-frames) |
 | Submit complete speech parts immediately and play them in order | [`SpeechPlayback`](runtime-modules.md#speechplaybackjs) and the [basic browser example](ai/browser-speech.md#play-a-complete-array-with-speechplayback) |
-| Preserve exact text in an explicit complete synthesis call | [Exact complete synthesis input](ai/browser-speech.md#exact-complete-synthesis-input) and [managed AI narration](sdk-api.md#managed-ai-narration) |
+| Preserve exact speech text and complete browser Kokoro audio | [Exact complete synthesis input](ai/browser-speech.md#exact-complete-synthesis-input) and [managed AI narration](sdk-api.md#managed-ai-narration) |
 | Select initial native window dimensions and resizing behavior | [Initial native window size](core-native-packaging.md#initial-native-window-size) and [Windows provider](sdk-api.md#createwindowsnativeprovider) |
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
 | Connect a browser to one Core transport | [Core browser client](core-client.md) |
@@ -61,8 +62,8 @@ alone does not make bare module names resolve in a browser.
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
 | Reuse dependency-ready native services without a renderer | [Core service composition](core-runtime.md#native-service-composition) and [existing ONNX owner](local-ai.md#native-service-owners) |
 | Compose application Core services during source development, independently of local AI | [Development Core services](core-development.md) |
-| Share one application service runtime between its native UI and MCP process | [Shared Core host](core-shared-host.md) |
-| Store complete browser model resources through one DBOPFS owner | [Model resources](ai/browser-decisions.md#shared-dbopfs-model-resources) and [speech routing](ai/browser-speech.md#ordinary-module-routing) |
+| Share one application service runtime between its ordinary native launch and MCP process | [Shared Core host](core-shared-host.md) and [native launch defaults](core-native-packaging.md#launch-time-locations) |
+| Store complete browser model resources, including the selected decision-runtime entry, through one DBOPFS owner | [Model resources](ai/browser-decisions.md#shared-dbopfs-model-resources) and [speech routing](ai/browser-speech.md#ordinary-module-routing) |
 | Observe committed storage changes across live application documents | [DBOPFS change subscriptions](runtime-modules.md#dbopfsjs) |
 | Cancel cold speech preparation while preserving other activation interests | [Prepared narration](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio) |
 | Own an explicitly selected native Codex App Server session | [Codex App Server](codex-app-server.md) |
@@ -85,7 +86,7 @@ alone does not make bare module names resolve in a browser.
 | Write, commit and push complete selected repository text | [Selected-text repository writing](core-repositories.md#write-commit-and-push-selected-text) |
 | Observe existing checkout configuration and capture an explicit remote/ref | [Repository configuration and selected targets](core-repositories.md#existing-checkout-configuration-and-selected-targets) |
 | Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
-| Pass host-selected state defaults and unchanged explicit launch values to services | [Launch-time locations](core-native-packaging.md#launch-time-locations) |
+| Resolve matching native state/workspace/endpoint defaults and preserve explicit launch values | [Launch-time locations](core-native-packaging.md#launch-time-locations) and [resolveNativeLaunchContext()](sdk-api.md#resolvenativelaunchcontext) |
 | Build a Windows executable without an OS checkout | [Windows executable packaging](core-native-packaging.md#windows-executable) |
 | Compose a Mac application with an architecture-matched host | [macOS application composition](core-native-packaging.md#macos-application-composition) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |

package/docs/reference/core-native-packaging.md

@@ -210,6 +210,64 @@ details and [the client contract](core-client.md) for native bridge integration.
 
 ## Launch-time locations
 
+An application can select defaults for ordinary double-click launch in its
+descriptor, without a replacement launcher or a required command-line file:
+
+```json
+{
+  "native": {
+    "launchContext": {
+      "sharedHost": {},
+      "dispatch": {"destination": "Moon Cheese Receiving Dock"}
+    }
+  }
+}
+```
+
+This is the `native` fragment of the application's complete descriptor. The
+optional `native.launchContext` object is copied intact to the portable
+manifest and generated Core entry. Its presence explicitly selects native
+location defaults. `sharedHost:{}` opts into the shared Core endpoint and log;
+omitting `sharedHost` retains stdio-owned Core lifetime. Omitting
+`native.launchContext` retains the previous generated-entry behavior entirely.
+Windows and macOS launchers use the same packaged defaults for native state
+selection, so an ordinary executable launch and external MCP can select the
+same app-owned Core.
+
+`resolveNativeLaunchContext({appId,context={}})` from `arcane-os/core/host` is
+the public, synchronous location owner for native applications and external MCP.
+It returns a new complete context and fills only omitted fields:
+
+| Field | SDK default |
+|---|---|
+| `stateRoot` on Windows | `%LOCALAPPDATA%/Arcane/<appId>`; standard home `AppData/Local` fallback when the environment value is absent |
+| `stateRoot` on macOS | `~/Library/Application Support/Arcane/<appId>` |
+| `stateRoot` on Linux | Absolute `$XDG_DATA_HOME/Arcane/<appId>`, otherwise `~/.local/share/Arcane/<appId>` |
+| `workspaceRoot` | `<resolved stateRoot>/Workspace` |
+| `sharedHost.endpoint`, only when `sharedHost` is selected | Windows named pipe `\\.\pipe\Arcane-` followed by the URL-encoded complete resolved state path; Linux/macOS socket `<resolved stateRoot>/core.sock` |
+| `sharedHost.logFile`, only when `sharedHost` is selected | `<resolved stateRoot>/Core.log` |
+
+Windows/macOS roots retain the existing native host locations. Linux is the
+portable Node host convention; an external composing host supplies its actual
+state root when it selects another location. Android and other host adaptations
+must supply `stateRoot` explicitly and own native IPC/process adaptation.
+The resolver never reads saved preferences, creates directories, changes the
+environment, starts services, or migrates existing data. The generated opted-in
+shared entry creates its selected state directory because its socket/log need
+that parent; application services continue to own workspace I/O. Custom
+endpoint/log parent directories retain the existing shared-host requirements.
+
+Explicit `stateRoot`, `workspaceRoot`, endpoint, log filename and additional
+fields remain authored values; the resolver derives omitted paths from the
+absolute selected state location. Relative explicit paths retain the caller's
+working-directory meaning, so UI and MCP callers must select the same location.
+No hashing, app-local OS path composition, directory scanning, or new repository
+location rule is involved. `resolveArcaneDataPaths()` continues to own its
+separate `ArcaneData/Repos` contract. A selected native context needs a nonempty
+string `appId` and state directory; a selected `sharedHost` must be an object.
+Malformed resolver inputs report `TypeError`; ordinary OS endpoint requirements
+remain at the IPC operation.
+
 For one app-owned Core shared by the native window and a separate MCP process,
 the launch context may explicitly select `sharedHost:{endpoint,logFile}`. The
 generated native child then connects through a stdio bridge, starting an
@@ -224,27 +282,36 @@ or `null`; the shared host replays that current listener to a newly attached
 macOS bridge, without restarting the server or retaining historical events.
 
 The generated Core entry accepts `--arcane-launch-config <path>`. The public
-`readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
-`arcane-os/core/host` reads that explicitly selected JSON object. A native host
+`readCoreLaunchContext({argv=process.argv.slice(2),defaults={},appId}={})`
+function in `arcane-os/core/host` reads that explicitly selected JSON object.
+Precedence is packaged `defaults`, then the native host's actual state-root
+argument, then every complete top-level field from the explicit JSON object.
+Nested records replace their default field as a whole; they are not deep-merged.
+An `appId` explicitly opts the result into `resolveNativeLaunchContext`; the
+generated entry supplies it only when `native.launchContext` is present.
+A native host
 can separately supply `--arcane-host-state-root <directory>` for the reader's
 `stateRoot` default. Every field in the explicit JSON object takes precedence
 unchanged, including an explicitly present `stateRoot` with a relative, null or
-other application-owned value. With neither argument the reader returns `{}`.
+other application-owned value on the ordinary non-resolving reader. With neither
+argument nor defaults/appId the reader still returns `{}`.
 Missing files, missing argument values and malformed JSON report their actual
 errors; the reader does not search for configuration, resolve or validate the
-state directory, rewrite the file or change the process environment.
+state directory, rewrite the file or change the process environment. The
+explicitly opted-in resolver supplies its documented defaults after this merge.
 
 The generated entry supplies an artifact-derived `appRoot` and then applies the
 complete explicit launch context. Every service factory receives that same
 object as its second argument, preserving its authored first argument. A
 launcher can supply the user's selected `workspaceRoot` and writable
 `stateRoot` at launch instead of embedding this machine's paths in an app
-package. The host owns those selections; the SDK does not choose a product's
-workspace, namespace, saved preferences or models. JSON values and additional
+package. Explicit product selections take precedence over the opted-in SDK
+location defaults. The SDK chooses no saved preference filename or model. JSON values and additional
 application-owned fields remain unchanged, including an app-selected
 `preferencesFile`. The state directory supplies no preference filename and
 triggers no stored-data discovery or migration. Linux and other composing hosts
-may pass the same separate argument; the reader chooses no platform directory.
+may pass the same separate argument; the ordinary reader chooses no platform
+directory until native resolution is explicitly selected.
 
 ## Selected local-AI runtimes
 

package/docs/reference/core-shared-host.md

@@ -146,8 +146,46 @@ events may change; applications own those domain methods and state.
 
 ## Native launch and platforms
 
-The generated portable Core entry keeps ordinary stdio behavior unless the
-explicit launch context contains:
+The generated portable Core entry keeps ordinary stdio behavior unless its
+selected launch context contains `sharedHost`. An application can opt in for
+ordinary packaged executable launch with `native.launchContext:{sharedHost:{}}`
+in its complete descriptor. The SDK supplies the app's platform state root,
+workspace, endpoint and diagnostic log through `resolveNativeLaunchContext`.
+The same public owner is available to external MCP:
+
+```js
+import {readCoreLaunchContext, connectSharedCoreHost} from 'arcane-os/core/host';
+
+const context = await readCoreLaunchContext({
+    appId: appDescriptor.id,
+    defaults: appDescriptor.native.launchContext
+});
+const connection = await connectSharedCoreHost({
+    endpoint: context.sharedHost.endpoint
+});
+// Invoke the application's actual services through connection.client.
+// Disconnect this MCP client without shutting down the application's host.
+await connection.close();
+```
+
+This example connects to a running native/headless host. The existing `start`
+option can start the packaged Core entry explicitly when independent MCP-first
+startup is needed; the entry applies those same packaged defaults. Pass the
+same explicit `--arcane-launch-config` file to both entries for user-selected
+locations. A caller that already owns a complete context can use the pure
+`resolveNativeLaunchContext({appId,context})` directly instead of reading argv.
+For MCP-first startup, prepare the returned `context.stateRoot` with Node's
+`mkdir(context.stateRoot,{recursive:true})` before selecting `start`, because
+the parent's startup diagnostic log opens before the headless child runs.
+This uses the resolved directory directly, without duplicating platform path
+rules. Pass `context.sharedHost.logFile` to that existing `start` record and
+the same launch file to the packaged Core command. Custom endpoint/log parent
+directories remain caller-selected.
+See [launch-time locations](core-native-packaging.md#launch-time-locations) for
+the exact platform defaults, precedence, location override and directory rules.
+No app must reconstruct OS directory rules.
+
+An explicit launch file can also select the existing full endpoint contract:
 
 ```json
 {
@@ -163,8 +201,9 @@ option, the native Core child is a stdio-to-shared-Core bridge. It connects or
 launches the same entry with `--arcane-core-headless`; the headless entry claims
 the endpoint before importing services. Closing the native window ends its
 bridge, while the independent Core host remains available. Service options and
-the complete launch context retain their existing values. There is no implicit
-shared mode or new application descriptor field.
+the complete launch context retain their existing values. Shared mode remains
+explicit: the new descriptor option selects defaults only for that application,
+and the existing no-option stdio path is unchanged.
 
 `startSharedCoreBridge({endpoint,start,input=process.stdin,
 output=process.stdout,signal,onError})` is also public. It returns

package/docs/reference/inventory/package-api.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.71.0",
+  "sdkVersion": "0.72.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 297,
+  "memberCount": 299,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -542,7 +542,7 @@
       "summary": "Explicit-load Laya and Julia-1 decisions with caller-selected precision, complete inputs and graph results.",
       "availability": "Browser module Workers and the selected Transformers.js backend; import/construction starts no model load",
       "protocol": "Caller-owned state/question/options rows; five-input decision graph; native Worker request/result lifecycle",
-      "normalization": "Full field tokenization, raw logits and unrounded softmax; dtype defaults to fp16 for Laya and fp32 for Julia, with explicit values forwarded unchanged. Optional existing SDK store routes actual loader resources through fetchResource outside cloned Worker configuration; stored mode disables competing model caches, preserves complete HTTP responses and joins resource cleanup before outstanding calls settle. Omission retains upstream loading; no decision-result persistence or precision fallback"
+      "normalization": "Full field tokenization, raw logits and unrounded softmax; dtype defaults to fp16 for Laya and fp32 for Julia, with explicit values forwarded unchanged. Optional existing SDK store routes the complete selected runtime entry and actual loader resources through fetchResource outside cloned Worker configuration. Each activation materializes unchanged entry source with JavaScript MIME and retains its original configured URL for later loads; its object URL is revoked after Worker termination. Stored mode disables competing model caches, preserves complete HTTP responses and joins runtime-entry/resource cleanup before outstanding calls settle. Runtime-entry HTTP failures retain error.response. Custom stored entries must support an object URL and changed import.meta.url; native absolute dependencies and custom factory imports outside upstream preloads remain browser-owned. Omission retains direct native module and upstream model loading; no decision-result persistence or precision fallback"
     },
     {
       "id": "root:acceptWebSocket",
@@ -1185,7 +1185,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Starts one owned browser development server for the selected application.",
+      "summary": "Starts one owned browser development server for the selected application, including native worker retirement when standalone source PWA is explicitly disabled and its root worker is absent.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2208,6 +2208,20 @@
       "protocol": "arcane-target-adapter/1, arcane-native-build-plan/1, or provider protocol",
       "normalization": "Normalized complete plan and result; target-specific artifact detail preserved"
     },
+    {
+      "id": "root:resolvePwaRetirementResponse",
+      "name": "resolvePwaRetirementResponse",
+      "displayName": "resolvePwaRetirementResponse()",
+      "kind": "function",
+      "signature": "async resolvePwaRetirementResponse({workspaceRoot=process.cwd(), appId}={})",
+      "entrypoints": ["arcane-os"],
+      "primaryImport": "arcane-os",
+      "group": "Workspace, doctor, repository, and server",
+      "summary": "Resolves the shared disabled-PWA root worker response for an existing custom source host, preserving authored workers and browser saved data.",
+      "availability": "Node; browser service-worker lifecycle remains browser-owned",
+      "protocol": "Node ESM and native service-worker lifecycle",
+      "normalization": "Current standalone descriptor and absent-root-worker selection; complete status/headers/body or null"
+    },
     {
       "id": "root:resolveWorkspace",
       "name": "resolveWorkspace",
@@ -2446,7 +2460,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Workspace, doctor, repository, and server",
-      "summary": "Starts an owned source or packaged browser server with complete selected routes, HTTPS by default, explicit HTTP selection, listener readiness and shutdown.",
+      "summary": "Starts an owned source or packaged browser server with complete selected routes, HTTPS by default, explicit HTTP selection, listener readiness and shutdown; explicitly disabled standalone source PWA retires an absent root worker through its native lifecycle.",
       "availability": "Node control plane; browser data plane",
       "protocol": "Node ESM",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -3708,7 +3722,7 @@
       "summary": "Creates a local-only Kokoro text-to-speech provider for the provider-neutral AI runtime.",
       "availability": "Browser with DBOPFS, Web Locks, Workers, object URLs, and caller-selected kokoro-js runtime/model content",
       "protocol": "arcane-ai-provider/2 tts/synthesize",
-      "normalization": "Independent load, status, request, unload, cancellation and disposal; optional ordinary model.voices records remain complete in the synchronous catalog without loading or constraining synthesis. Provider-native requests return 24000 Hz Float32Array PCM, while shared AI.js requests use wav and return complete Uint8Array audio/wav data; never selects a cloud fallback"
+      "normalization": "Independent load, status, request, unload, cancellation and disposal; optional ordinary model.voices records remain complete in the synchronous catalog without loading or constraining synthesis. Upstream text normalization and phonemization remain selected-runtime behavior. Tokenization disables truncation; short inputs use one inference and longer inputs send every content token through ordered engine-capacity segments, retaining required outer padding and all generated audio in order. Segments share the slot's existing model and disposal owner. Request-local cancellation is observed between segments and before returning audio; an already-running upstream inference may finish. Provider-native requests return 24000 Hz Float32Array PCM, while shared AI.js requests use wav and return complete Uint8Array audio/wav data; never selects a cloud fallback"
     },
     {
       "id": "browser-speech:createBrowserSpeechArtifactGraph",
@@ -4530,19 +4544,33 @@
       "protocol": "arcane/1 preferences methods and schemaVersion 1 entries file",
       "normalization": "Binding identity is exactly equal to the named createPreferencesService export"
     },
+    {
+      "id": "core-host:resolveNativeLaunchContext",
+      "name": "resolveNativeLaunchContext",
+      "displayName": "resolveNativeLaunchContext()",
+      "kind": "function",
+      "signature": "resolveNativeLaunchContext({appId,context={}}={})",
+      "entrypoints": ["arcane-os/core/host"],
+      "primaryImport": "arcane-os/core/host",
+      "group": "Native Core host composition",
+      "summary": "Resolves matching per-app native state, workspace and optional shared endpoint defaults for packaged UI and external MCP.",
+      "availability": "Node native locations on Windows/Linux/macOS; Android and other hosts supply stateRoot and native adaptation",
+      "protocol": "Pure native launch-context resolution and existing local IPC",
+      "normalization": "Returns a new complete context with only omitted stateRoot/workspaceRoot and selected sharedHost endpoint/log fields filled; preserves explicit values and additional payloads. Native launchContext presence opts generated entry into resolution; omitted sharedHost retains stdio. No I/O, saved-state discovery, process startup, migration or ArcaneData/Repos change. Malformed selected appId/stateRoot/sharedHost inputs report TypeError; platform IPC errors remain operation-owned."
+    },
     {
       "id": "core-host:readCoreLaunchContext",
       "name": "readCoreLaunchContext",
       "displayName": "readCoreLaunchContext()",
       "kind": "function",
-      "signature": "async readCoreLaunchContext({argv=process.argv.slice(2)}={})",
+      "signature": "async readCoreLaunchContext({argv=process.argv.slice(2),defaults={},appId}={})",
       "entrypoints": ["arcane-os/core/host"],
       "primaryImport": "arcane-os/core/host",
       "group": "Native Core host composition",
-      "summary": "Reads explicit launch JSON with the separately supplied native host stateRoot default for service launch context.",
+      "summary": "Combines packaged defaults, actual native host stateRoot and complete explicit launch JSON, with optional native location resolution.",
       "availability": "Node, including the selected external-entry SEA launcher",
       "protocol": "Explicit launch arguments and JSON configuration",
-      "normalization": "Optional --arcane-host-state-root <directory> supplies the stateRoot default; every explicit --arcane-launch-config JSON field takes precedence unchanged, including relative or null stateRoot and application-owned preferencesFile. Returns an empty record with neither argument; surfaces missing argument values, file and JSON failures; performs no directory selection, path resolution, configuration search, rewrite, migration or environment mutation"
+      "normalization": "Precedence is defaults, then --arcane-host-state-root, then complete top-level --arcane-launch-config JSON fields; nested values replace without deep merging or payload rewriting. Explicit appId invokes resolveNativeLaunchContext; ordinary calls retain relative/null/custom state values and return an empty record with no inputs. Missing arguments, file/JSON errors and malformed records reject. No configuration search, file rewrite, migration or environment mutation; generated native.launchContext explicitly selects the resolver."
     },
     {
       "id": "core-host:startCoreHost",

package/docs/reference/pwa.md

@@ -207,6 +207,66 @@ The server path uses the existing portable Node serving owner, and browser
 retirement requires the browser's native service-worker support and an existing
 registration eligible for that update.
 
+### Retirement through an existing custom host
+
+An application that already serves its source through `node-http-server` can
+keep that server and delegate only its root worker route to the public SDK
+representation owner:
+
+```js
+import {Server} from 'node-http-server';
+import {resolvePwaRetirementResponse} from 'arcane-os';
+
+// This is the application's existing subclass and workspace root.
+class DragonMailServer extends Server {
+    async onRequest(request, response) {
+        const pathname = new URL(request.originalUrl || request.url, 'http://localhost').pathname;
+        if ((request.method === 'GET' || request.method === 'HEAD') && pathname === '/arcane-sw.js') {
+            const retirement = await resolvePwaRetirementResponse({
+                workspaceRoot: this.workspaceRoot,
+                appId: 'dragon-mail'
+            });
+            if (retirement) {
+                response.statusCode = retirement.statusCode;
+                for (const [name, value] of Object.entries(retirement.headers)) {
+                    response.setHeader(name, value);
+                }
+                await this.serve(request, response, retirement.body);
+                return true;
+            }
+        }
+        // Keep the application's other routes here before ordinary static serving.
+        return false;
+    }
+}
+```
+
+Use the application's actual root and ID. The SDK reads the current
+`arcane-packager.json` and, for standalone `appsRoot:"."`, the authored root
+`arcane-app.json`; only an absent authored descriptor selects
+`arcane-package.json`. Reads use the existing descriptor projection and package
+contract without rewriting either file or requiring a stale generated projection
+to equal a newly edited authored descriptor. `appId` is optional; when supplied,
+it must match that descriptor's ID.
+
+The result is `null` for multi-app workspaces, omitted or enabled PWA, an omitted
+`pwa.enabled` field (including `{pwa:{}}`), and any existing root `arcane-sw.js`
+entry. The author's explicit `pwa.enabled:false` choice and an `ENOENT`
+worker result produce `{statusCode, headers, body}`: status `200`, the shared
+JavaScript content type, `Cache-Control: no-cache`, and the complete existing
+retirement script. Malformed configuration and other filesystem failures reject
+instead of selecting another descriptor or treating a file as absent.
+
+The host applies those headers directly; it must not replace `no-cache` with
+its unrelated response defaults or treat a former enabled worker's validator as
+validation of this response. The existing `serve()` method owns response
+completion and HEAD body omission. Keep this exact worker route at the serving
+origin that owns the registration; application HTTPS redirects and other routes
+remain application-owned. This API starts no server, writes no file, performs
+no offline-inventory scan, and touches no browser data. It shares the same
+response policy and worker generator as the SDK source server. The native
+activation and existing-page lifetime limits above also apply here.
+
 ### Authored host root and app entry
 
 An authored `index.html` at the source host root keeps `/` separate from the

package/docs/reference/sdk-api.md

@@ -57,7 +57,7 @@ runtime layouts.
 | `arcane-os/core/runtime` | App-neutral native Core dispatcher and service lifecycle. |
 | `arcane-os/core/development` | App-service composition and document-owned Core transport during source development, independently of local AI. |
 | `arcane-os/core/stdio` | Framed Node stdio transport with graceful runtime drain. |
-| `arcane-os/core/host` | Node-only reusable Core host lifecycle with explicitly supplied services. |
+| `arcane-os/core/host` | Node-only reusable Core host lifecycle, app-selected native launch defaults and shared native location resolution. |
 | `arcane-os/codex/app-server` | Explicit native Codex App Server session, complete live turns, server requests and recovery. |
 | `arcane-os/mcp/stdio` | Node MCP STDIO server for app-owned tools and static resources. |
 | `arcane-os/core/repositories` | Native persistent ArcaneData paths, connected working repositories and scoped non-secret Git identity configuration. |
@@ -429,7 +429,8 @@ The remaining data-only subpaths are eight JSON Schemas and package metadata.
 | `connectSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node local IPC and optional explicit headless startup |
 | `runSharedCoreHost()` | function | `arcane-os/core/host` | Shared Core host | Node headless entry and optional parent startup IPC |
 | `startSharedCoreBridge()` | function | `arcane-os/core/host` | Shared Core host | Node readable/writable streams and local IPC |
-| `readCoreLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node; reads explicitly selected launch JSON |
+| `readCoreLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node; combines packaged defaults, host state and explicitly selected launch JSON |
+| `resolveNativeLaunchContext()` | function | `arcane-os/core/host` | Native Core host composition | Node native paths; Android supplies its adapted state root |
 | `resolveArcaneDataPaths()` | function | `arcane-os/core/repositories` | Native repository workspaces | Node on Windows, Linux and macOS; Android supplies its data root |
 | `createRepositoryWorkspace()` | function | `arcane-os/core/repositories` | Native repository workspaces | Node with Git; Android requires host process adaptation |
 | `readGitIdentity()` | function | `arcane-os/core/repositories` | Native repository workspaces | Node with Git; Android requires host process adaptation |
@@ -4205,6 +4206,39 @@ There is no history scan, app loop, diagnostic payload store or automatic retry.
 The authored `test/websocket.test.mjs` fixtures cover this boundary; source
 inspection is distinct from executing them or verifying a browser deployment.
 
+## resolvePwaRetirementResponse()
+
+```text
+async resolvePwaRetirementResponse({workspaceRoot=process.cwd(), appId}={})
+```
+
+Import from `arcane-os`. This Node API supplies the shared disabled-PWA worker
+response to an application's existing server without starting or replacing it.
+It reads the current standalone workspace configuration and root authored
+descriptor, using the package descriptor only when the authored file is absent.
+The optional `appId` must match the selected descriptor. It uses the existing
+configuration contracts, performs no writes and rereads current configuration
+on each call; there is no retained cache, timer, subscription or dispose handle.
+
+It returns `null` for a non-standalone workspace, omitted or enabled PWA, an
+omitted `pwa.enabled` field, or an existing root `arcane-sw.js` entry. The author's
+explicit `pwa.enabled:false` choice plus an `ENOENT` root
+worker produces `{statusCode:200, headers, body}`, with the existing JavaScript
+content type, `Cache-Control: no-cache`, and the complete retirement script.
+Configuration/JSON errors and other filesystem failures reject. The result
+carries no prior worker `Last-Modified` validator.
+
+The caller owns its exact GET/HEAD `/arcane-sw.js` route and applies the supplied
+status, headers and body through its existing `node-http-server` public
+`serve()` path. A `null` result leaves normal routing intact. There is no request
+payload transformation, server listener, generated file, cache/storage cleanup,
+client enumeration or reload. The worker skips waiting on installation and
+unregisters its own registration on activation; existing-page controller timing
+remains browser-owned. The [custom-host PWA guide](pwa.md#retirement-through-an-existing-custom-host)
+shows the complete hook and preservation contract. The Node filesystem path is
+portable across Windows, Linux and macOS; Android needs its normal Node host
+adaptation, and browser retirement requires native service-worker support.
+
 ## startDevServer()
 
 ### Overview
@@ -7925,29 +7959,90 @@ The default binding from `arcane-os/core/diarization` is exactly the named
 import createDiarizationService from 'arcane-os/core/diarization';
 ```
 
+## resolveNativeLaunchContext()
+
+### Overview
+
+Resolves one application's native state, workspace and optional shared endpoint
+through the same public owner used by its packaged executable and external MCP.
+This synchronous function performs no I/O, saved-state discovery, process start
+or migration.
+
+### Signature and result
+
+```text
+resolveNativeLaunchContext({appId,context={}}={})
+```
+
+Import from `arcane-os/core/host`. The result is a new complete context with
+omitted fields filled. Windows defaults to `%LOCALAPPDATA%/Arcane/<appId>`
+(home `AppData/Local` fallback), macOS to
+`~/Library/Application Support/Arcane/<appId>`, and portable Linux Node to
+absolute `$XDG_DATA_HOME/Arcane/<appId>` or `~/.local/share/Arcane/<appId>`.
+Android and other adapted hosts provide their actual `stateRoot` and own native
+IPC/process adaptation.
+
+An omitted `workspaceRoot` becomes `<absolute selected stateRoot>/Workspace`.
+Only a selected `sharedHost` object receives a default endpoint and log file:
+Windows uses a named pipe containing the URL-encoded complete absolute state
+path; Linux/macOS use `<absolute selected stateRoot>/core.sock`. The log is
+`<absolute selected stateRoot>/Core.log`. Explicit fields, additional payloads
+and explicit workspace values remain unchanged. Relative explicit paths retain
+the caller's working-directory meaning. `appId` and the selected state path
+must be nonempty strings; a selected `sharedHost` must be an object. Malformed
+inputs report `TypeError`; native endpoint failures belong to the IPC operation.
+
+```javascript
+import {resolveNativeLaunchContext} from 'arcane-os/core/host';
+
+const context = resolveNativeLaunchContext({
+    appId: 'moon-cheese-post',
+    context: {sharedHost: {}}
+});
+// Use context.sharedHost.endpoint for the native UI and external MCP.
+// An explicit context.workspaceRoot or context.stateRoot remains selected.
+```
+
+In a complete app descriptor, `native.launchContext:{sharedHost:{}}` selects
+these defaults for ordinary packaged executable launch. Omitting `sharedHost`
+keeps stdio-owned lifetime; omitting `native.launchContext` preserves the prior
+generated-entry path. The selected shared entry creates its state directory
+for socket/log use; application services own workspace I/O. MCP-first startup
+prepares that returned state directory before the existing `start` option opens
+its log. No caller needs to reconstruct platform paths. The separate
+`resolveArcaneDataPaths()` repository-location contract remains unchanged.
+See [launch-time locations](core-native-packaging.md#launch-time-locations) and
+[shared native/MCP hosting](core-shared-host.md#native-launch-and-platforms).
+
 ## readCoreLaunchContext()
 
 ### Overview
 
-Reads the complete JSON object explicitly selected by
-`--arcane-launch-config <path>`, with an optional separately supplied native host
-state-directory default. It does not search for application configuration.
+Combines complete packaged defaults, a separately supplied native host state
+directory and the complete JSON object selected by `--arcane-launch-config`.
+An explicit `appId` selects the native resolver; ordinary calls remain a
+configuration reader without automatic location selection.
 
 ### Signature and result
 
 ```text
-async readCoreLaunchContext({argv=process.argv.slice(2)}={})
+async readCoreLaunchContext({argv=process.argv.slice(2),defaults={},appId}={})
 ```
 
-Import it from `arcane-os/core/host`. `--arcane-host-state-root <directory>`
-supplies a `stateRoot` default; every field from the explicit launch JSON object
-then takes precedence unchanged, including a relative, null or other explicitly
-present `stateRoot`. With neither argument, the promise resolves to `{}`.
-A missing argument value, unreadable launch file, malformed JSON or non-object
-value rejects. Relative launch-file paths use the process working directory.
-The reader does not choose, resolve or validate the state directory, rewrite
-content, discover or migrate stored data, or mutate the environment. An
-application-selected `preferencesFile` remains a separate unchanged field.
+Import from `arcane-os/core/host`. Precedence is `defaults`, then
+`--arcane-host-state-root <directory>`, then every complete top-level field from
+the explicit launch JSON object. Nested fields replace rather than deep-merge.
+The original file and its payload remain unchanged. Supplying `appId` applies
+`resolveNativeLaunchContext` to that merged record; its defaults and input
+contract then apply. Without `appId`, relative, null and other explicit state
+values retain the prior reader semantics. With no arguments or defaults, the
+ordinary call still resolves to `{}`.
+
+Missing argument values, unreadable files, malformed JSON, non-object defaults
+or launch records reject. Relative launch-file paths use the working directory.
+The reader searches no other configuration, rewrites no content, migrates no
+data and changes no environment. Application-owned fields such as
+`preferencesFile` retain their complete values.
 
 ```javascript
 import {readCoreLaunchContext} from 'arcane-os/core/host';
@@ -7956,12 +8051,13 @@ const launchContext = await readCoreLaunchContext();
 ```
 
 The generated entry supplies artifact-derived `appRoot`, then applies the whole
-explicit context and passes the same object as every service factory's second
-argument. Authored service options remain the first argument. Workspace/state
-locations and additional fields belong to the launcher/application. Windows and
-Mac launchers forward their actual host-selected state directory through the
-separate argument; other composing hosts may use the same seam. This JavaScript
-contract does not establish a compiled host or matching release archive. See
+context and passes the same object as every service factory's second argument.
+Authored service options remain the first argument. It supplies the descriptor's
+`native.launchContext` as `defaults` and the app ID only when that optional
+field is present. Matching Windows and macOS launchers apply the same packaged
+defaults before explicit launch JSON and forward their actual state directory;
+other composing hosts can use the same public seam. Compiled host availability
+and native execution are separate from this JavaScript contract. See
 [launch-time locations](core-native-packaging.md#launch-time-locations).
 
 ## resolveArcaneDataPaths()
@@ -9550,13 +9646,26 @@ No decisions are inserted into chat history or durable storage.
 
 Optional `store` is an existing SDK DBOPFS model or speech store exposing
 `fetchResource(input, options)`. It remains outside cloned Worker configuration.
-The selected loader routes its actual model/configuration/tokenizer resources
-through that owner and disables competing model caches in this explicit mode.
-Omission preserves ordinary upstream loading. Native ESM imports retain their
-platform loader. Resource progress counts closed shards; cancellation joins
-resource cleanup before outstanding `load()`/`evaluate()` calls settle.
+Explicit activation first stores the complete selected `runtime.moduleUrl`
+entry and materializes it as a JavaScript object URL without rewriting source.
+The configured original URL remains the resource selection for later loads.
+The selected loader also routes its actual model/configuration/tokenizer
+resources through that owner and disables competing model caches in this mode.
+Each activation revokes its runtime object URL after terminating its Worker on
+cancellation, failure, unload or disposal. Resource progress counts closed
+shards; cancellation joins runtime-entry and resource cleanup before outstanding
+`load()`/`evaluate()` calls settle. Runtime-entry HTTP failures report
+`ARCANE_DECISION_RUNTIME_DOWNLOAD_FAILED` with the complete stored response in
+`error.response` for developer diagnostics.
 `unload()` and `dispose()` acknowledge their state transition synchronously.
 
+The default runtime entry is self-contained. Custom stored entries must work
+from an object URL: entry materialization changes `import.meta.url` and does not
+rewrite relative imports or original-location support-file references. Native
+absolute ESM dependencies and custom factory imports outside upstream preloads
+remain browser-owned. Omitting `store` preserves direct native module loading
+and ordinary upstream model loading. See [shared model resources](ai/browser-decisions.md#shared-dbopfs-model-resources).
+
 ### Example
 
 ```js
@@ -10442,6 +10551,18 @@ mono 16-bit PCM. Unsupported formats fail
 `ARCANE_AI_UNSUPPORTED_RESPONSE_FORMAT`; malformed adapter audio fails
 `ARCANE_AI_INVALID_PROVIDER_RESULT`. Unknown fields and accessors reject as malformed.
 
+The Kokoro adapter retains upstream text normalization and phonemization, then
+tokenizes without truncation and sends every content token through the selected
+engine. Short inputs use one inference; longer inputs use ordered segments
+within that engine's capacity and return all generated audio in order. Each
+segment retains the engine's required outer padding, voice-style selection and
+speed. The segments share the slot's existing loaded model and disposal owner;
+they do not create another model or provider-pool slot. Cancellation is checked
+between inference segments and before returning audio; already-running upstream
+inference may finish. This engine transport is distinct from the SDK's optional
+`textFormat:'plain'` input treatment. See [complete synthesis input](ai/browser-speech.md#exact-complete-synthesis-input)
+for the selected tokenizer/model contract and upstream revision behavior.
+
 Automatic execution tries a complete WebNN NPU pool when
 `navigator.ml.createContext` is exposed, then WebGPU when `navigator.gpu` is
 exposed, then CPU through WASM. A failed candidate is cleaned up before a fresh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.71.2",
+  "version": "0.73.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/schemas/arcane-app.schema.json

@@ -132,6 +132,10 @@
           }
         },
         "localAI": { "$ref": "#/$defs/localAI" },
+        "launchContext": {
+          "type": "object",
+          "description": "Optional complete native launch defaults. Presence opts into SDK per-app native locations; sharedHost:{} explicitly selects the shared endpoint. Explicit launch JSON fields take precedence unchanged."
+        },
         "window": {
           "type": "object",
           "additionalProperties": false,

package/src/app-descriptor.mjs

@@ -254,7 +254,7 @@ function validateNativeWindow(value){
 }
 
 function validateNative(value,appId){
-    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog','localAI','services','window']),'descriptor.native');
+    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog','localAI','services','window','launchContext']),'descriptor.native');
     if(!NATIVE_TYPES.has(value.type))fail('descriptor.native.type is unsupported.');
     const icon=value.icon===null?null:normalizeRelativePath(value.icon,'descriptor.native.icon');
     if(!is.integer(value.order)||value.order<0){
@@ -265,6 +265,9 @@ function validateNative(value,appId){
     });
     const documentCatalog=validateDocumentCatalog(value.documentCatalog);
     const window=validateNativeWindow(value.window);
+    if(value.launchContext!==undefined&&!isObject(value.launchContext)){
+        fail('descriptor.native.launchContext must be an object.');
+    }
     let services;
     if(value.services!==undefined){
         if(!is.array(value.services))fail('descriptor.native.services must be an array.');
@@ -279,6 +282,7 @@ function validateNative(value,appId){
         order:value.order,
         bundledApps,
         ...(window===undefined?{}:{window}),
+        ...(value.launchContext===undefined?{}:{launchContext:value.launchContext}),
         ...(services===undefined?{}:{services}),
         ...(value.localAI===undefined?{}:{localAI:normalizeLocalAIConfig(value.localAI)}),
         ...(documentCatalog?{documentCatalog}:{})
@@ -416,6 +420,7 @@ export function projectNativeDescriptor(descriptor,{source}={}){
         ...(value.native.documentCatalog?{documentCatalog:value.native.documentCatalog}:{}),
         ...(value.native.services===undefined?{}:{services:value.native.services}),
         ...(value.native.window===undefined?{}:{window:value.native.window}),
+        ...(value.native.launchContext===undefined?{}:{launchContext:value.native.launchContext}),
         ...(value.native.localAI===undefined?{}:{localAI:value.native.localAI}),
         include:[...value.package.include]
     };
@@ -462,6 +467,7 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             bundledApps:[...(native.bundledApps??[])],
             ...(native.services===undefined?{}:{services:native.services}),
             ...(native.window===undefined?{}:{window:native.window}),
+            ...(native.launchContext===undefined?{}:{launchContext:native.launchContext}),
             ...((packageManifest.localAI??native.localAI)===undefined?{}:{localAI:packageManifest.localAI??native.localAI}),
             ...(native.documentCatalog?{documentCatalog:native.documentCatalog}:{})
         },

package/src/core/host.mjs

@@ -1,4 +1,6 @@
 import {readFile} from 'node:fs/promises';
+import {homedir} from 'node:os';
+import path from 'node:path';
 import Is from 'strong-type';
 import {createCoreRuntime} from './runtime.mjs';
 import {startCoreStdio} from './stdio.mjs';
@@ -7,32 +9,90 @@ export {startSharedCoreHost, connectSharedCoreHost, runSharedCoreHost, startShar
 
 const is = new Is(false);
 
+/** Resolve one app's native locations without creating or migrating data. */
+export function resolveNativeLaunchContext({appId, context = {}} = {}) {
+    if (!is.string(appId) || !appId) throw new TypeError('Native launch resolution requires an appId.');
+    if (context === null || !is.object(context) || is.array(context)) {
+        throw new TypeError('Native launch context must be an object.');
+    }
+    let stateRoot = context.stateRoot;
+    if (stateRoot === undefined) {
+        const home = homedir();
+        switch (process.platform) {
+            case 'win32':
+                stateRoot = path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'Arcane', appId);
+                break;
+            case 'darwin':
+                stateRoot = path.join(home, 'Library', 'Application Support', 'Arcane', appId);
+                break;
+            case 'linux': {
+                const xdg = process.env.XDG_DATA_HOME;
+                stateRoot = path.join(xdg && path.isAbsolute(xdg) ? xdg : path.join(home, '.local', 'share'), 'Arcane', appId);
+                break;
+            }
+            default:
+                throw new TypeError('This native host must supply its persistent stateRoot.');
+        }
+    }
+    if (!is.string(stateRoot) || !stateRoot) throw new TypeError('Native stateRoot must be a nonempty directory path.');
+    const root = path.resolve(stateRoot);
+    const resolved = {
+        ...context,
+        stateRoot,
+        workspaceRoot: context.workspaceRoot === undefined ? path.join(root, 'Workspace') : context.workspaceRoot
+    };
+    if (context.sharedHost !== undefined) {
+        if (context.sharedHost === null || !is.object(context.sharedHost) || is.array(context.sharedHost)) {
+            throw new TypeError('Native sharedHost must be an object.');
+        }
+        // Encode the complete selected Windows path as a pipe-name component;
+        // Unix IPC uses an ordinary file in that same persistent app directory.
+        const endpoint = process.platform === 'win32'
+            ? '\\\\.\\pipe\\Arcane-' + encodeURIComponent(root)
+            : path.join(root, 'core.sock');
+        resolved.sharedHost = {
+            ...context.sharedHost,
+            endpoint: context.sharedHost.endpoint === undefined ? endpoint : context.sharedHost.endpoint,
+            logFile: context.sharedHost.logFile === undefined ? path.join(root, 'Core.log') : context.sharedHost.logFile
+        };
+    }
+    return resolved;
+}
+
 /**
- * The host's separate state-root argument supplies a launch-context default.
+ * Packaged defaults precede the host's actual state-root argument.
  * Every field in an explicitly selected launch JSON object takes precedence
  * unchanged; field meanings belong to the launch owner and individual services.
+ * appId explicitly selects native location resolution; ordinary calls keep the
+ * existing read-only launch-file contract without choosing any locations.
  */
-export async function readCoreLaunchContext({argv = process.argv.slice(2)} = {}) {
+export async function readCoreLaunchContext({argv = process.argv.slice(2), defaults = {}, appId} = {}) {
+    if (defaults === null || !is.object(defaults) || is.array(defaults)) {
+        throw new TypeError('Core launch defaults must be an object.');
+    }
     const stateFlag = argv.indexOf('--arcane-host-state-root');
-    const defaults = {};
+    const context = {...defaults};
     if (stateFlag !== -1) {
         const stateRoot = argv[stateFlag + 1];
         if (stateRoot === undefined || stateRoot === '') {
             throw new TypeError('--arcane-host-state-root requires a directory.');
         }
-        defaults.stateRoot = stateRoot;
+        context.stateRoot = stateRoot;
     }
     const flag = argv.indexOf('--arcane-launch-config');
-    if (flag === -1) return defaults;
-    const filename = argv[flag + 1];
-    if (filename === undefined || filename === '') {
-        throw new TypeError('--arcane-launch-config requires a filename.');
-    }
-    const context = JSON.parse(await readFile(filename, 'utf8'));
-    if (context === null || !is.object(context) || is.array(context)) {
-        throw new TypeError('Core launch configuration must be a JSON object.');
+    let selected = context;
+    if (flag !== -1) {
+        const filename = argv[flag + 1];
+        if (filename === undefined || filename === '') {
+            throw new TypeError('--arcane-launch-config requires a filename.');
+        }
+        const explicit = JSON.parse(await readFile(filename, 'utf8'));
+        if (explicit === null || !is.object(explicit) || is.array(explicit)) {
+            throw new TypeError('Core launch configuration must be a JSON object.');
+        }
+        selected = {...context, ...explicit};
     }
-    return {...defaults, ...context};
+    return appId === undefined ? selected : resolveNativeLaunchContext({appId, context: selected});
 }
 
 /** Compose app services with the shared dispatcher and draining transport. */

package/src/core/hosts/macos/ArcaneLauncher.m

@@ -231,14 +231,25 @@ typedef NS_ENUM(NSUInteger, ArcaneDiagnosticStream) {
     NSString *appID = ArcaneRequiredString(app, @"id", error);
     if (!appID) return NO;
     _title = [app[@"displayName"] isKindOfClass:NSString.class] ? app[@"displayName"] : appID;
+    id defaults = manifest[@"launchContext"];
+    if (defaults && ![defaults isKindOfClass:NSDictionary.class]) {
+        *error = ArcaneLauncherError(@"CORE_LAUNCH_MANIFEST_INVALID", @"The native launchContext must be an object.", defaults);
+        return NO;
+    }
+    NSMutableDictionary *launchContext = defaults ? [defaults mutableCopy] : [NSMutableDictionary dictionary];
     if (_launchFilename) {
-        _launchContext = ArcaneReadRecord([NSURL fileURLWithPath:_launchFilename], error);
-        if (!_launchContext) return NO;
+        NSDictionary *explicitContext = ArcaneReadRecord([NSURL fileURLWithPath:_launchFilename], error);
+        if (!explicitContext) return NO;
+        [launchContext addEntriesFromDictionary:explicitContext];
     }
+    _launchContext = launchContext;
+    // The opted-in Node resolver uses HOME when supplied; retain the previous
+    // native default unchanged for applications without launchContext.
+    NSString *nativeHome = defaults ? (NSProcessInfo.processInfo.environment[@"HOME"] ?: NSHomeDirectory()) : NSHomeDirectory();
     id selectedState = _launchContext[@"stateRoot"];
     _stateRoot = [selectedState isKindOfClass:NSString.class]
         ? ArcaneAbsolutePath(selectedState, _workingDirectory)
-        : [[NSHomeDirectory() stringByAppendingPathComponent:@"Library/Application Support/Arcane"] stringByAppendingPathComponent:appID];
+        : [[nativeHome stringByAppendingPathComponent:@"Library/Application Support/Arcane"] stringByAppendingPathComponent:appID];
     [self scheduleDiagnostics];
     NSString *clientPath = ArcaneRequiredString(client, @"source", error);
     if (!clientPath) return NO;

package/src/core/hosts/windows/ArcaneLauncher.cs

@@ -57,13 +57,33 @@ namespace Arcane.Core.Hosts.Windows
                 Dictionary<string, object> host = manifest.TryGetValue("host", out hostValue) ? hostValue as Dictionary<string, object> : null;
                 string icon = host != null && host.TryGetValue("icon", out iconValue) ? iconValue as string : null;
 
-                // Core rereads this exact selected file. Do not normalize,
-                // rewrite, filter or copy the application's launch record.
-                Dictionary<string, object> launchContext = launchFilename == null ? null : ReadRecord(launchFilename);
+                // Native UI and generated Core use the same packaged defaults.
+                // Core rereads the explicit file; every explicit field wins.
+                Dictionary<string, object> launchContext = manifest.ContainsKey("launchContext")
+                    ? new Dictionary<string, object>(RequiredRecord(manifest, "launchContext"))
+                    : new Dictionary<string, object>();
+                if (launchFilename != null)
+                {
+                    foreach (KeyValuePair<string, object> field in ReadRecord(launchFilename))
+                        launchContext[field.Key] = field.Value;
+                }
+                string defaultStateBase = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
+                if (manifest.ContainsKey("launchContext"))
+                {
+                    // Match the public Node resolver for this opt-in contract,
+                    // including an explicitly selected process environment.
+                    defaultStateBase = Environment.GetEnvironmentVariable("LOCALAPPDATA");
+                    if (String.IsNullOrEmpty(defaultStateBase))
+                    {
+                        string home = Environment.GetEnvironmentVariable("USERPROFILE");
+                        if (String.IsNullOrEmpty(home)) home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+                        defaultStateBase = Path.Combine(home, "AppData", "Local");
+                    }
+                }
                 object stateRoot;
-                string profileParent = launchContext != null && launchContext.TryGetValue("stateRoot", out stateRoot) && stateRoot is string
+                string profileParent = launchContext.TryGetValue("stateRoot", out stateRoot) && stateRoot is string
                     ? Path.GetFullPath((string)stateRoot)
-                    : Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "Arcane", appId);
+                    : Path.Combine(defaultStateBase, "Arcane", appId);
                 OpenDiagnostics(Path.Combine(profileParent, "Diagnostics"));
                 ArcaneHostOptions options = new ArcaneHostOptions
                 {

package/src/dev-server.mjs

@@ -17,7 +17,7 @@ import {
     readWorkspaceAssetVersion,resolveAssetReference,rewriteAssetReferences,versionAssetUrl
 } from './import-map.mjs';
 import {createPwaArtifacts,selectPwaFiles} from './pwa.mjs';
-import {createPwaRetirementWorkerScript} from './pwa-worker.mjs';
+import {createPwaRetirementResponse} from './pwa-retirement.mjs';
 
 const is = new Is(false);
 
@@ -1074,6 +1074,7 @@ async function startOwnedDevServer({
         currentSourceRoutes = {
             ...routeSet,
             app: manifest,
+            pwaExplicitlyDisabled: (authored ? value.package?.pwa : value.pwa)?.enabled === false,
             rootDocument,
             startPath: applicationSourcePath(routeSet.config,routeSet.appId,manifest.entry),
             mappings: mappings.map(
@@ -1303,26 +1304,18 @@ async function startOwnedDevServer({
                 return;
             }
             if (mode === 'source' && selectedRoutes.config.appsRoot === '.'
-                && selectedRoutes.app?.pwa?.enabled === false && target.path === '/arcane-sw.js') {
-                let rootWorkerExists = true;
-                try {
-                    await lstat(path.join(selectedRoutes.workspaceRoot, 'arcane-sw.js'));
-                } catch (error) {
-                    if (error?.code !== 'ENOENT') throw error;
-                    rootWorkerExists = false;
-                }
-                if (!rootWorkerExists) {
-                    response.setHeader('Cache-Control', 'no-cache');
-                    await serveGeneratedRepresentation(
-                        fileServer,
-                        request,
-                        response,
-                        {
-                            // A former enabled worker's date cannot validate this retirement script.
-                            contentType: contentTypes.js,
-                            body: createPwaRetirementWorkerScript
-                        }
-                    );
+                && selectedRoutes.pwaExplicitlyDisabled && target.path === '/arcane-sw.js') {
+                const retirement = await createPwaRetirementResponse({
+                    workspaceRoot: selectedRoutes.workspaceRoot,
+                    pwa: selectedRoutes.app.pwa
+                });
+                if (retirement) {
+                    response.statusCode = retirement.statusCode;
+                    for (const [name, value] of Object.entries(retirement.headers)) {
+                        response.setHeader(name, value);
+                    }
+                    // A former enabled worker's date cannot validate this retirement script.
+                    await fileServer.serve(request, response, retirement.body);
                     return;
                 }
             }

package/src/index.mjs

@@ -146,6 +146,7 @@ export {
 } from './workspace.mjs';
 export {materializeInstalledSdkRuntime} from './installed-sdk-runtime.mjs';
 export {startDevServer} from './dev-server.mjs';
+export {resolvePwaRetirementResponse} from './pwa-retirement.mjs';
 export {createDevelopmentCore} from './core/development.mjs';
 export {startSourceExampleServer} from './source-server.mjs';
 export {acceptWebSocket} from './websocket.mjs';

package/src/native/portable-layout.mjs

@@ -151,6 +151,7 @@ export async function copyCoreRuntime(root, files, signal, {
 }
 
 export function coreEntrySource(application, version, services, {localAI, runtimes = [], packagedWeb = false} = {}) {
+    const launchDefaults = application.native?.launchContext;
     const imageSelected = localAI?.runtimes?.some(function selectedImage(requirement) {
         return (typeof requirement === 'string' ? requirement : requirement.id) === 'stable-diffusion.cpp';
     }) ?? false;
@@ -199,6 +200,7 @@ export function coreEntrySource(application, version, services, {localAI, runtim
         "import {fileURLToPath} from 'node:url';",
         "import path from 'node:path';",
         "import {isSea} from 'node:sea';",
+        ...(launchDefaults === undefined ? [] : ["import {mkdir} from 'node:fs/promises';"]),
         "import {readCoreLaunchContext, startCoreHost, runSharedCoreHost, startSharedCoreBridge} from 'arcane-os/core/host';",
         '',
         ...(localAI === undefined ? [] : [
@@ -241,9 +243,15 @@ export function coreEntrySource(application, version, services, {localAI, runtim
             '        return resolved;',
             '    }),'
         ]),
-        '    ...await readCoreLaunchContext()',
+        launchDefaults === undefined ? '    ...await readCoreLaunchContext()'
+            : `    ...await readCoreLaunchContext({appId: ${JSON.stringify(application.id)}, defaults: JSON.parse(${JSON.stringify(JSON.stringify(launchDefaults))})})`,
         '};',
         '',
+        ...(launchDefaults === undefined ? [] : [
+            '// The shared endpoint and diagnostic log require their selected state directory.',
+            'if (context.sharedHost !== undefined) await mkdir(context.stateRoot, {recursive: true});',
+            ''
+        ]),
         ...(packagedWeb ? ['let packagedWeb;', ''] : []),
         'async function createServices(register) {',
         `    const [${imports.map(function binding(selection) { return selection.binding; }).join(', ')}] = await Promise.all([`,

package/src/native/portable-provider.mjs

@@ -197,6 +197,7 @@ export function createPortableNativeProvider({services, packagedWeb = false, web
                     webRoot: 'app',
                     start: release.manifest?.app?.start ?? './index.html',
                     ...(appDescriptor.native?.window === undefined ? {} : {window: {...appDescriptor.native.window}}),
+                    ...(appDescriptor.native?.launchContext === undefined ? {} : {launchContext: appDescriptor.native.launchContext}),
                     core: {
                         entry: 'runtime/arcane-core.mjs', transport: 'stdio', protocol: 'arcane/1', services: selectedServices,
                         ...(localAI === undefined ? {} : {localAIRuntimes: bundled.runtimes})

package/src/pwa-retirement.mjs

@@ -0,0 +1,53 @@
+import {lstat, readFile} from 'node:fs/promises';
+import path from 'node:path';
+import contentTypes from 'node-http-server/mime-types';
+import {APP_DESCRIPTOR_NAME, projectPackageManifest} from './app-descriptor.mjs';
+import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
+import {inspectWorkspaceProfile} from './workspace.mjs';
+import {createPwaRetirementWorkerScript} from './pwa-worker.mjs';
+
+export async function resolvePwaRetirementResponse({workspaceRoot = process.cwd(), appId} = {}) {
+    const profile = await inspectWorkspaceProfile(workspaceRoot);
+    if (profile.config.appsRoot !== '.') return null;
+
+    let manifestPath = path.join(profile.workspaceRoot, APP_DESCRIPTOR_NAME);
+    let source;
+    let authored = true;
+    try {
+        source = await readFile(manifestPath, 'utf8');
+    } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        authored = false;
+        manifestPath = path.join(profile.workspaceRoot, APP_CONFIG_NAME);
+        source = await readFile(manifestPath, 'utf8');
+    }
+    const value = JSON.parse(source);
+    const manifest = authored ? projectPackageManifest(value) : value;
+    validateAppConfig(
+        manifest, appId ?? manifest.id, profile.config, manifestPath
+    );
+    // Normalization defaults an omitted enabled field to false. Retirement
+    // instead consumes the author's explicit choice from the original record.
+    const pwa = authored ? value.package.pwa : value.pwa;
+    return createPwaRetirementResponse({workspaceRoot: profile.workspaceRoot, pwa});
+}
+
+// Source serving already owns a current descriptor snapshot. Reuse that snapshot
+// without introducing another descriptor read or changing its refresh lifetime.
+export async function createPwaRetirementResponse({workspaceRoot, pwa}) {
+    if (pwa?.enabled !== false) return null;
+    try {
+        await lstat(path.join(workspaceRoot, 'arcane-sw.js'));
+        return null;
+    } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+    }
+    return {
+        statusCode: 200,
+        headers: {
+            'Content-Type': contentTypes.js,
+            'Cache-Control': 'no-cache'
+        },
+        body: createPwaRetirementWorkerScript()
+    };
+}