arcane-os 0.55.0 → 0.56.0

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

@@ -3657,7 +3657,7 @@
       "entrypoints": ["arcane-os/core/contracts"],
       "primaryImport": "arcane-os/core/contracts",
       "group": "Core protocol contracts",
-      "summary": "Describes the public fields on Core request, response, event and cancellation frames.",
+      "summary": "Describes the public fields on Core request, response, event, cancellation and runtime.replay control frames.",
       "availability": "Node and browser/bundler",
       "protocol": "arcane/1 wire descriptions",
       "normalization": "Descriptive data only; it does not admit methods, validate application policy or create a transport"
@@ -3709,14 +3709,14 @@
       "name": "createCoreClient",
       "displayName": "createCoreClient()",
       "kind": "function",
-      "signature": "createCoreClient({global=globalThis,transport=null,eventOwner=arcaneEvents,eventOwnerReady,autoConnect=true,onError}={})",
+      "signature": "createCoreClient({global=globalThis,transport=null,eventOwner=arcaneEvents,eventOwnerReady,autoConnect=true,replayRuntimeState=false,onError}={})",
       "entrypoints": ["arcane-os/core/client"],
       "primaryImport": "arcane-os/core/client",
       "group": "Core browser client",
       "summary": "Creates one correlated Arcane Core RPC client with explicit transport, readiness, events, cancellation and lifetime ownership.",
       "availability": "Browser and native WebView JavaScript hosts; custom transports require a callable send(frame)",
       "protocol": "arcane/1 over the selected host transport",
-      "normalization": "Preserves complete request, result and event data; rejects invalid transports before readiness, retains FIFO handoff to the shared event owner and reports transport failures that arrive after request settlement"
+      "normalization": "Preserves complete request, result and event data; retains FIFO event-owner handoff; failTransport(error) settles pending RPCs and acknowledgements with the complete failure and releases the client lifetime; opt-in replayRuntimeState sends one observed nonblocking runtime.replay control after transport readiness"
     },
     {
       "id": "core-client:createCoreFacade",
@@ -3741,24 +3741,38 @@
       "entrypoints": ["arcane-os/core/client"],
       "primaryImport": "arcane-os/core/client",
       "group": "Core browser client",
-      "summary": "Installs one synchronous global Arcane facade and native receive callback for the selected renderer lifetime.",
+      "summary": "Installs one synchronous global Arcane facade, native receive callback and terminal transport-failure callback for the selected renderer lifetime.",
       "availability": "Browser and native WebView JavaScript hosts",
       "protocol": "arcane/1 renderer facade",
-      "normalization": "Repeated installation returns the same client; closing releases subscriptions, callbacks, timers and pending renderer requests without killing Core"
+      "normalization": "Repeated installation returns the same client; close/failTransport release owned resources and restore prior globals only while still owned; __arcaneTransportFailed preserves the complete host failure without killing Core"
+    },
+    {
+      "id": "core-client:getInstalledCoreClient",
+      "name": "getInstalledCoreClient",
+      "displayName": "getInstalledCoreClient()",
+      "kind": "function",
+      "signature": "getInstalledCoreClient(global=globalThis)",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Returns the exact live SDK-installed client or null without installing, connecting or changing globals.",
+      "availability": "Browser and native WebView JavaScript hosts",
+      "protocol": "arcane/1 renderer client ownership",
+      "normalization": "Recognizes ESM and classic SDK installation identity; returns null after close or terminal failure and does not treat a foreign Arcane facade as an SDK client"
     },
     {
       "id": "core-classic-source:createCoreClassicSource",
       "name": "createCoreClassicSource",
       "displayName": "createCoreClassicSource()",
       "kind": "function",
-      "signature": "async createCoreClassicSource({eventOwnerModuleURL}={})",
+      "signature": "async createCoreClassicSource({eventOwnerModuleURL,replayRuntimeState=false}={})",
       "entrypoints": ["arcane-os/core/classic-source"],
       "primaryImport": "arcane-os/core/classic-source",
       "group": "Core classic client projection",
       "summary": "Generates the native host's classic injection script from the installed canonical Core client and contracts.",
       "availability": "Node; generated source runs in browser and native WebView renderers",
       "protocol": "arcane/1 classic-script injection",
-      "normalization": "Returns the complete canonical client projection; installs synchronous facade shapes while deferring only the shared event-owner module connection when document parsing is incomplete"
+      "normalization": "Returns the complete canonical client projection; installs synchronous facade shapes while deferring only the event-owner module connection when document parsing is incomplete; forwards explicit runtime replay selection with a false default"
     },
     {
       "id": "core-runtime:createCoreRuntime",
@@ -3772,7 +3786,7 @@
       "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
       "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
       "protocol": "arcane/1 dispatcher and service lifecycle",
-      "normalization": "Starts services independently, preserves request correlation and complete results/errors, cancels only request-lifetime work and waits accepted service-lifetime responses before ordered service drain and disposal"
+      "normalization": "Starts services independently, preserves complete results/errors, cancels only request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order"
     },
     {
       "id": "core-stdio:encodeCoreFrame",

package/docs/reference/protocols.md

@@ -88,9 +88,11 @@ Explicit host document lists use the separate root-exported
 described below; they do not enter app discovery.
 
 The application dependency boundary is conditional. Only an application that
-actually consumes Arcane declares one exact published `arcane-os` version in
-its own `package.json` and resolves it through that project's normal install
-into its own `node_modules`. An application that does not currently consume
+actually consumes Arcane declares `arcane-os` in its own `package.json` and
+resolves it through that project's normal install into its own `node_modules`.
+During development the declaration tracks `latest`; the lockfile and installed
+package record the exact selected version. An explicitly selected production
+build may declare an exact version. An application that does not currently consume
 Arcane adds no `arcane-os` dependency solely because of this rule; the user or
 governing task may direct that application to adopt Arcane later, at which point
 the same app-owned package, install, projection, and artifact boundary applies.
@@ -381,10 +383,11 @@ layouts; the default nested scaffold continues to use its development dependency
 ## Installed SDK runtime materialization
 
 `materializeInstalledSdkRuntime()` is the Node entrypoint for refreshing one
-external workspace's checked-in `arcane/` projection from its one exact
-installed SDK declaration. Import the function through the dependency key that
+external workspace's checked-in `arcane/` projection from its one declared and
+installed SDK dependency. Import the function through the dependency key that
 the workspace actually declares: `arcane-os` for the canonical package name or,
-for example, `arcane-sdk` for the exact `npm:arcane-os@<version>` alias. No
+for example, `arcane-sdk` for the development alias `npm:arcane-os@latest`. The
+lockfile and installed package retain the exact resolved version. No
 application- or Arcane OS-local copier owns this operation.
 
 The operation resolves that declaration while holding the shared
@@ -563,8 +566,8 @@ exactly `dependencyName`, `packageSource`,
 `canonicalPackageRoot`, `packageName`, `packageVersion`, `runtimeRoot`,
 and `browserRuntimeRoot`. A
 workspace may use the canonical dependency name or one npm alias such as
-`npm:arcane-os@0.51.1`; the installed package manifest identifies `arcane-os`
-and supplies its actual version. The resolver requires one declaration and a
+`npm:arcane-os@latest`; the installed package manifest identifies `arcane-os`
+and supplies its actual exact version. The resolver requires one declaration and a
 direct physical installation with runtime and browser-runtime directories.
 The application's normal npm declaration and lockfile own version selection.
 
@@ -999,9 +1002,12 @@ reachable.
 
 ### macOS
 
-No macOS target, native bridge, Core host, artifact, or run contract is exposed
-by this SDK version. A browser may still run browser-only application code, but
-that does not create a native Arcane host or satisfy a native capability.
+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.
 
 ## Development and remote HTTP transport
 
@@ -1083,8 +1089,11 @@ The common contract ends where platform truth must remain different:
   artifact kind, and some diagnostic/result fields remain platform-specific;
 - unsupported platforms fail or return a documented unsupported state; they do
   not run an unrelated browser implementation as a substitute;
-- this SDK version requires a selected checkout and Core to provide the current
-  native plan's protocol, version, feature, capability, method, and provider;
+- 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;
 - 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

@@ -206,6 +206,23 @@ manifest carries release information. Non-PWA and native packaging use the same
 [clean local resource URLs](asset-versioning.md). Native packaging does not
 generate the browser PWA worker, installation manifest or registration bootstrap.
 
+## Package without browser PWA output
+
+Select `browserPwa:false` for an artifact, such as an application directory
+inside an extension-owned root. The package omits `arcane.webmanifest`,
+`arcane-offline.json`, `arcane-sw.js`, and `arcane-pwa.mjs`. Before native-module
+processing, it removes active SDK-marked `data-arcane-pwa` scripts and manifest
+relationships that resolve to that package's `arcane.webmanifest` from the
+selected application document set.
+
+This is a package-output choice, not a source or saved-setting change. It
+preserves unrelated manifest links and link relationships, comments, templates,
+other inactive HTML, unselected documents, and authored PWA configuration. The
+application remains responsible for any extension manifest, permissions,
+background process, toolbar launcher, or other outer host. See the
+[native-module output contract](protocols.md#native-module-package-output) and
+[`packageApp()` options](sdk-api.md#packageapp) for the complete boundary.
+
 ## Development and hosting
 
 Use the ordinary `arcane dev --app <id>` command after editing the selected

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.55.0",
+  "version": "0.56.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

@@ -48,6 +48,16 @@
         "pwa": { "$ref": "#/$defs/pwa" },
         "include": { "$ref": "#/$defs/nonemptyPathList" },
         "exclude": { "$ref": "#/$defs/pathList" },
+        "nativeResources": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["include"],
+          "description": "Additional literal application-relative paths for a selected nonbrowser target. Exclude applies only to this additional selection. Native-only files retain their complete original content and do not enter browser document or PWA processing. Omission or an empty include preserves existing selection and output behavior.",
+          "properties": {
+            "include": { "$ref": "#/$defs/pathList" },
+            "exclude": { "$ref": "#/$defs/pathList" }
+          }
+        },
         "shared": {
           "type": "array",
           "minItems": 1,

package/schemas/arcane-package.schema.json

@@ -88,6 +88,16 @@
     "exclude": {
       "$ref": "#/$defs/pathList"
     },
+    "nativeResources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["include"],
+      "description": "Additional literal application-relative paths for a selected nonbrowser target. Exclude applies only to this additional selection. Native-only files retain their complete original content and do not enter browser document or PWA processing. Omission or an empty include preserves existing selection and output behavior.",
+      "properties": {
+        "include": { "$ref": "#/$defs/pathList" },
+        "exclude": { "$ref": "#/$defs/pathList" }
+      }
+    },
     "shared": {
       "type": "array",
       "uniqueItems": true,

package/src/app-descriptor.mjs

@@ -111,13 +111,21 @@ function validateLocalAIModelPolicy(value,label){
 
 function validatePackage(value,appId){
     assertOnlyKeys(value,new Set([
-        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa','documents'
+        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa','documents','nativeResources'
     ]),'descriptor.package');
     const entry=normalizeRelativePath(value.entry,'descriptor.package.entry');
     const documents=normalizeAppDocuments(value.documents,'descriptor.package.documents');
     if(!['static','adapter'].includes(value.strategy))fail('descriptor.package.strategy must be static or adapter.');
     const include=relativePaths(value.include,'descriptor.package.include',{required:true});
     const exclude=relativePaths(value.exclude??[],'descriptor.package.exclude');
+    let nativeResources;
+    if(value.nativeResources!==undefined){
+        assertOnlyKeys(value.nativeResources,new Set(['include','exclude']),'descriptor.package.nativeResources');
+        nativeResources={
+            include:relativePaths(value.nativeResources.include,'descriptor.package.nativeResources.include'),
+            exclude:relativePaths(value.nativeResources.exclude??[],'descriptor.package.nativeResources.exclude')
+        };
+    }
     if(!include.some(candidate=>entry===candidate||entry.startsWith(`${candidate}/`))){
         fail('descriptor.package.entry must be covered by descriptor.package.include.');
     }
@@ -140,6 +148,7 @@ function validatePackage(value,appId){
         strategy:value.strategy,
         include,
         exclude,
+        ...(nativeResources===undefined?{}:{nativeResources}),
         shared,
         ...(value.pwa===undefined?{}:{pwa:normalizePwaConfig(value.pwa)}),
         ...(adapter?{adapter}:{}),
@@ -331,6 +340,10 @@ export function projectPackageManifest(descriptor){
         ...(value.package.pwa===undefined?{}:{pwa:value.package.pwa}),
         include:[...value.package.include],
         exclude:[...value.package.exclude],
+        ...(value.package.nativeResources===undefined?{}:{nativeResources:{
+            include:[...value.package.nativeResources.include],
+            exclude:[...value.package.nativeResources.exclude]
+        }}),
         shared:[...value.package.shared],
         ...(value.package.adapter?{adapter:value.package.adapter}:{})
     };
@@ -391,6 +404,10 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             ...(packageManifest.pwa===undefined?{}:{pwa:packageManifest.pwa}),
             include:[...packageManifest.include],
             exclude:[...(packageManifest.exclude??[])],
+            ...(packageManifest.nativeResources===undefined?{}:{nativeResources:{
+                include:[...packageManifest.nativeResources.include],
+                exclude:[...(packageManifest.nativeResources.exclude??[])]
+            }}),
             shared:[...packageManifest.shared],
             ...(packageManifest.adapter?{adapter:packageManifest.adapter}:{})
         },

package/src/app-layout.mjs

@@ -9,8 +9,12 @@ export function resolveAppRoot(workspaceRoot, config, appId) {
     return path.resolve(workspaceRoot, appRelativeRoot(config, appId));
 }
 
-export function resolvePackageOutputRoot(workspaceRoot, config, app) {
-    return path.resolve(workspaceRoot, app.outputDirectory ?? `${config.distRoot}/${app.id}`);
+export function resolvePackageOutputRoot(workspaceRoot, config, app, {target='browser', outputDirectory}={}) {
+    const nativeSelection=target!=='browser'&&app.nativeResources?.include.length>0;
+    const selectedDirectory=outputDirectory??(nativeSelection
+        ?`${config.distRoot}/.native/${target}/${app.id}`
+        :app.outputDirectory??`${config.distRoot}/${app.id}`);
+    return path.resolve(workspaceRoot,selectedDirectory);
 }
 
 export function appBaseHref(workspaceRoot, appRoot, document = 'index.html') {

package/src/core/hosts/arcane-core-loader.cjs

@@ -0,0 +1,2 @@
+// This ordinary filesystem module retains Node's asynchronous ESM loader.
+module.exports = import('./arcane-core.mjs');