arcane-os 0.57.0 → 0.59.0

package/docs/reference/protocols.md

@@ -47,12 +47,14 @@ These protocols normalize orchestration and results. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
-Portable CLI operations load the installed SDK's
-`arcane-os/native/portable-provider` by default. Explicit `--arcane-root`
-selection retains the checkout provider route; executable targets still need
-their platform provider/toolchain. `arcane-os/core/host` composes the reusable
-native runtime with explicitly supplied app services. Neither export is a
-browser import, executable host or installer. The synchronous classic facade
+Portable CLI operations load `arcane-os/native/portable-provider`; Windows x64
+loads `arcane-os/native/windows-provider`, both from the installed SDK by
+default. The Windows provider assembles the matching precompiled WebView2/SEA
+host release asset. Explicit `--arcane-root` selection retains the checkout
+route; Linux and Android still need their platform provider/toolchain.
+`arcane-os/core/host` composes the reusable native runtime with explicitly
+supplied app services. These Node entries remain separate from browser imports;
+portable itself remains a non-executable payload. The synchronous classic facade
 and browser-safe client retain their separate public entries. Integrated
 shared checks keep their existing Arcane OS development provider.
 
@@ -1047,10 +1049,15 @@ or a dependency is ready.
 
 ### Microsoft NT / WebView2
 
-The renderer uses the WebView2 host messaging surface. The host binds one app
-identity and native policy to the session before Core dispatch. Microsoft NT
-can expose managed-service and privileged platform operations that do not exist
-in an ordinary browser.
+The SDK Windows host mounts the selected app at a virtual HTTPS origin and
+injects the canonical classic facade before application scripts. Ordered
+`arcane/1` requests and complete responses cross its owned WebView2/Core bridge;
+each connected document requests authoritative runtime/service replay. Its
+selected service composition supplies the actual methods. Closing the window
+cancels renderer requests and drains accepted service work before Core exits.
+See [Windows executable packaging](core-native-packaging.md#windows-executable).
+Arcane OS can separately compose product policy and privileged services; the
+generic SDK host does not copy that product composition.
 
 ### Linux / WebKitGTK
 
@@ -1070,12 +1077,13 @@ reachable.
 
 ### macOS
 
-No macOS executable target, native bridge, platform host, artifact, or run
-contract is exposed by this SDK version. A browser may still run browser-only
-application code. A separately composed macOS host may use the reusable Node
-Core runtime, framed stdio transport, host composition, and portable payload,
-but those SDK primitives do not create a native bridge or executable host and
-do not by themselves satisfy a native capability.
+This version includes Foundation-only `ArcaneCoreProcess` source for an
+explicit executable, framed pipes and graceful child lifecycle. It supplies no
+macOS renderer bridge, executable target, artifact or run command. A separately
+composed macOS host may combine that source with the reusable Node runtime,
+stdio transport, host composition and portable payload. Source delivery does
+not establish compilation or execution on macOS. See
+[the macOS process-source contract](core-native-packaging.md#macos-process-source).
 
 ## Development and remote HTTP transport
 
@@ -1159,9 +1167,10 @@ The common contract ends where platform truth must remain different:
   not run an unrelated browser implementation as a substitute;
 - the portable target defaults to the installed SDK provider and assembles a
   non-executable payload without an Arcane OS checkout;
-- executable native targets require their explicit checkout/provider, and the
-  composed host must supply the protocol, version, features, capabilities,
-  methods, and services that its application contract requires;
+- Windows x64 defaults to the installed SDK's matching precompiled host;
+  Linux/Android retain explicit checkout/providers. Every composed host must
+  supply the protocol, version, features, capabilities, methods and services
+  that its application contract requires;
 - that current-build compatibility does not promise that a future SDK will accept
   this Core or that this SDK will accept a future Core.
 

package/docs/reference/pwa.md

@@ -94,14 +94,81 @@ packaging use that layout directly:
   packaged installation ID remains `./`, and an explicit `manifest.id` remains
   authoritative. An ID identifies the installation; it does not generate a
   directory or a redirect.
-- Authored resources follow their normal include/exclude selection. Generation
-  does not delete existing files, stored application data, or worker caches.
+- Authored resources follow their normal include/exclude selection. Ordinary
+  generation preserves existing files, stored application data, and worker caches.
+  Explicit retirement of confirmed generated source output is described below.
 
 Generated and offline app files are committed. GitHub Actions consume those
 committed files rather than generating them. Actual multi-app workspaces keep
 their explicit `appsRoot: "apps"` layout. This source/package contract does not
 establish any particular installed application's browser lifecycle.
 
+### Disable source PWA generation and retire generated output
+
+Set `package.pwa.enabled:false` in `arcane-app.json` (or `pwa.enabled:false` in
+an authored schema-1 `arcane-package.json`), then run the public import-map
+operation. For standalone `appsRoot:"."` applications, disabled refresh removes
+active `data-arcane-pwa` registration scripts and matching manifest relationships
+marked `data-arcane-manifest` from the selected application documents. Root source
+generation marks only manifest links it newly inserts; it does not claim an
+existing unmarked link as its own. A wholly omitted `pwa` record does not select
+source retirement.
+
+By default, unmarked manifest references and all existing PWA files remain in
+place. This preserves authored resources that happen to use the standard names.
+Older SDK source generation emitted an unmarked manifest link. When the
+application owner has established that this link and the four standard root
+outputs are SDK-generated, use the same public toolchain with an explicit
+ownership declaration:
+
+```js
+import {createToolchain} from 'arcane-os';
+
+const toolchain = createToolchain({workspaceRoot: process.cwd(), appId: 'my-app'});
+await toolchain.importMap({retireGeneratedPwa: true});
+```
+
+Before retirement, remove any explicit entries for these generated outputs from
+the application's `package.include` selection. They are generated output, not
+required source input; leaving a deleted file as a required input would make the
+next inspection fail. Keep authored selection changes with the application
+owner. Confirm that unselected documents or separately hosted pages do not still
+need the retiring files; this operation does not rewrite those pages.
+
+With PWA disabled, `retireGeneratedPwa:true` also removes selected-document
+manifest relationships resolving to the root `arcane.webmanifest`, including
+older unmarked generated links, and deletes exactly these confirmed generated
+files at the application root:
+
+- `arcane.webmanifest`
+- `arcane-offline.json`
+- `arcane-sw.js`
+- `arcane-pwa.mjs`
+
+The option is an application-owner declaration of generated ownership, not a
+filename-based inference. Omit it when any listed file or matching manifest
+reference is authored or its ownership is unknown. It is available through
+`createToolchain().importMap()` and `executeOperation('import-map', options)`;
+there is no new CLI flag. The ordinary CLI refresh performs marked-reference
+retirement only. An enabled descriptor ignores this retirement option and
+continues normal generation.
+
+With the source selection updated, repeated retirement accepts already-absent
+generated files. The
+`import-map.root-files.completed` event reports the paths actually removed in
+`retiredPwa`. Re-enabling PWA regenerates its normal root output and references.
+The operation leaves other files (including a separate `manifest.json`), other
+link relationships, inactive HTML, unselected documents, SDK mappings, and
+application content unchanged. It never unregisters an already registered
+service worker, clears caches, or changes browser saved data. Existing browser
+registrations therefore keep their own lifecycle; source retirement is not a
+claim that an installed browser PWA was removed. Package-output behavior below
+is unchanged.
+
+Reference updates finish before file removal begins. Cancellation or a file
+error is reported without undoing earlier completed changes; a later call can
+finish retirement. The operation does not claim an all-or-nothing transaction.
+
 ### Authored host root and app entry
 
 An authored `index.html` at the source host root keeps `/` separate from the
@@ -261,11 +328,14 @@ origin root and starts at the selected app entry: `/index.html` for a standalone
 root app with that entry, or `/apps/<id>/<entry>` for a nested app. Use one
 selected app per development origin. The SDK uses `node-http-server` for source
 and packaged-preview serving, including conditional resource responses.
-Arcane development servers default to HTTPS, including localhost, and packaged
-browser previews require HTTPS. Configure the workspace certificate pair before
+Arcane development servers and packaged browser previews default to HTTPS,
+including localhost. Configure the workspace certificate pair before
 starting the ordinary command; see [development HTTPS setup](cli.md#development-https-setup).
 Explicit source-only `arcane dev --http` serves the same generated PWA routes
 without loading certificates; see [explicit HTTP development](cli.md#explicit-http-development).
+API callers may select `http:true` in packaged mode to serve the existing
+packaged web root, without generating or changing its PWA files. Browser
+secure-context and installation requirements remain browser-owned.
 `--public` selects the IPv4 wildcard bind address; it does not enable PWA
 configuration, change manifest metadata, or determine browser installability.