coakka-v2-connector-electron 2.5.3 → 3.1.1

package/CONSUMING.md

@@ -1,10 +1,12 @@
 # Consuming CoAkka Runtime Connector For Electron
 
-This is the Electron connector for the polyglot, multi-language, multi-platform
-CoAkka Runtime ecosystem. Install it through your normal application package
-feed. Electron remains the application framework dependency; this package owns
-the CoAkka runtime intent bridge and consumes the Node connector as the
-main-process runtime host.
+## Version `3.1.1`
+
+Electron `3.1.1` is the first Electron connector release on Core generation
+`3.1`. It installs `coakka-v2-connector-node@3.1.2` as an exact dependency.
+The Node connector includes Core 3.1 r2, build
+`6789dd16210fc01f17cca4d2b66a592d1ac79121`, ABI 1, for macOS ARM64,
+Linux ARM64/x64 and Windows ARM64/x64.
 
 Use the package only from the Electron main process and preload boundary:
 
@@ -13,3 +15,44 @@ Use the package only from the Electron main process and preload boundary:
 - renderer: call `window.coakka.intent(...)`
 
 Do not import the runtime connector directly from renderer code.
+
+Use Electron 42 or later and let npm install the declared Node dependency
+when you install the Electron connector.
+
+Keep `contextIsolation: true`, `nodeIntegration: false` and `sandbox: true` on
+the application window. Compile your preload source into one CommonJS file
+with a JavaScript bundler: include `coakka-v2-connector-electron/preload` in the
+bundle and leave only `electron` external. Neither a runtime owner nor native
+library loading belongs in the preload. The renderer receives only the
+intent methods exposed by the context bridge, not general-purpose IPC access.
+
+Supply `authorize` when registering main-process IPC handlers. Check the
+window, main frame and trusted document URL using Electron's main-process
+event; return literal `true` only for an accepted sender. Do not trust an
+intent's `source` string as sender identity. Reject untrusted navigation and
+window creation according to the application's policy.
+
+Remove registered IPC handlers and await runtime close on every exit path.
+A close does not cancel or join an application handler already executing; cancel
+and join business tasks separately before releasing their application resources.
+Late handler results cannot reply through the closing native owner.
+A failed duplicate handler registration preserves the existing handler.
+Startup snapshots report the runtime's accepted values; omitted CPU and
+connection preferences use `AUTO` and `MULTIPLEXED`. Renderer intent deadlines
+remain bounded (2 seconds when omitted, at most 30 seconds), and each IPC
+batch defaults to the accepted runtime queue capacity capped at 64 values.
+The inherited ask path requires no host worker-pool tuning; one lazy bounded
+main-process scheduler advances Core-owned tickets without allocating one
+worker for every ask.
+An explicit batch maximum may not exceed that capacity or 256. Batches run in
+input order and are not atomic: completed items are not rolled back on failure.
+These intent limits belong to the Electron application boundary; they are
+not a second native capability or configuration table.
+
+## Shutdown timing
+
+Closing retires native work before releasing its resources. Host scheduling
+and storage affect that latency: macOS qualification observed occasional
+Runtime/File shutdowns taking about 2.4 seconds. That observation is not a
+hard maximum. Release application resources only after close has returned
+or its Promise has settled.

package/PACKAGE-LICENSE.md

@@ -28,4 +28,4 @@ substantially equivalent infrastructure service.
 It does not replace either license.
 
 Public guidance and stable links are available in the
-[CoAkka package licensing guide](https://github.com/phuong-tran/coakka-samples/blob/main/docs/package-licensing.md).
+[CoAkka package licensing guide](https://github.com/phuong-tran/coakka-samples/blob/83c4dd7de7290df064e79fcbbca1f470458142a0/docs/common/package-licensing.md).

package/README.md

@@ -1,7 +1,7 @@
 # CoAkka Runtime Connector For Electron
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/phuong-tran/coakka-samples/main/docs/assets/brand/coakka-logo.png" alt="CoAkka" width="480">
+  <img src="https://raw.githubusercontent.com/phuong-tran/coakka-samples/main/docs/common/assets/brand/coakka-logo.png" alt="CoAkka" width="480">
 </p>
 
 **This is the Electron connector in the polyglot, multi-language,
@@ -12,15 +12,22 @@ contract used by Node.js, the JVM, Python, Go, C#, Rust, Swift, and other
 connector lanes.
 
 Kubernetes is supported but not required. Use the public
-[Ecosystem Overview](https://github.com/phuong-tran/coakka-samples/blob/main/docs/ecosystem-overview.md)
-and [Compatibility Matrix](https://github.com/phuong-tran/coakka-publish/blob/main/docs/compatibility-matrix.md)
+[Ecosystem Overview](https://github.com/phuong-tran/coakka-samples/blob/main/docs/common/ecosystem-overview.md)
+and [Compatibility Matrix](https://github.com/phuong-tran/coakka-publish/blob/main/docs/coakka-runtime/reference/compatibility-matrix.md)
 to select an exact package and native platform tuple.
 Start with the [CoAkka Documentation](https://github.com/phuong-tran/coakka-samples/blob/main/docs/README.md)
 for concepts, integration paths, operations, and runnable samples.
 
-Minimum hosts: Electron 42 and Node.js 22 in the Electron main process. The
-native runtime remains owned by main-process code; renderer and preload code
-do not load it directly.
+Use Electron 42 or later. The Electron main process owns the runtime. Preload
+and renderer code use a small intent API over IPC.
+
+## Version `3.1.1`
+
+Electron `3.1.1` is the first Electron connector release on Core generation
+`3.1`. Its exact dependency `coakka-v2-connector-node@3.1.2` includes Core
+3.1 r2, build `6789dd16210fc01f17cca4d2b66a592d1ac79121`, ABI 1. npm installs
+the Node dependency automatically. Its native images cover macOS ARM64,
+Linux ARM64/x64 and Windows ARM64/x64.
 
 ## New To CoAkka
 
@@ -36,25 +43,14 @@ Use these public repositories to orient first:
 | `coakka-samples` | Runnable examples and code you can inspect first. | https://github.com/phuong-tran/coakka-samples |
 | `coakka-publish` | Released packages, native archives, manifests, checksums, compatibility matrix, and release notes. | https://github.com/phuong-tran/coakka-publish |
 
-Run the matching sample:
+Install the connector with npm.
 
 ```sh
-git clone https://github.com/phuong-tran/coakka-samples.git
-cd coakka-samples
-bash run.sh runtime electron basic
+npm install coakka-v2-connector-electron@3.1.1
 ```
 
-No-checkout npm smoke:
-https://github.com/phuong-tran/coakka-samples/blob/main/docs/first-npm-smoke.md
-
-Samples docs directory:
-https://github.com/phuong-tran/coakka-samples/tree/main/docs
-
-That smoke explains the runtime mental model first: keep real HTTP or IPC at
-the app edge, but replace fake backend HTTP used only for work owned by the
-same app or team with a CoAkka target and explicit reply/deadletter behavior.
-
-The boundary is intentionally strict:
+The following example routes an intent from a sandboxed window to a named
+handler in the main process and returns the handler's reply to the renderer.
 
 - renderer JavaScript sends an intent through `ipcRenderer.invoke`
 - preload exposes only a small `coakka.intent(...)` API
@@ -69,16 +65,18 @@ The main-process options can forward the shared `connectionStrategy` and
 `security` startup specs. Capability/config/security getters and atomic apply
 results are exposed on `ElectronRuntimeIntentBridge`; renderer/preload code
 still never receives credential material. See
-[Connection Strategies](https://github.com/phuong-tran/coakka-samples/blob/main/docs/connection-strategies.md),
-[TLS and mTLS](https://github.com/phuong-tran/coakka-samples/blob/main/docs/tls-and-mtls.md),
-and [Troubleshooting](https://github.com/phuong-tran/coakka-samples/blob/main/docs/troubleshooting.md).
+[Connection Strategies](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/reference/connection-strategies.md),
+[TLS and mTLS](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/reference/tls-and-mtls.md),
+and [Troubleshooting](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/operations/troubleshooting.md).
 
 ## Main Process
 
 ```js
-import { ipcMain } from "electron";
+import { BrowserWindow, ipcMain } from "electron";
+import { pathToFileURL } from "node:url";
 import {
   ElectronRuntimeIntentBridge,
+  localRoute,
   registerElectronIntentIpcHandler,
 } from "coakka-v2-connector-electron";
 
@@ -86,7 +84,7 @@ const target = "samples.electron.intent.echo";
 const bridge = ElectronRuntimeIntentBridge.start({
   systemName: "electron-app",
   nodeId: "electron-app-main",
-  defaultTarget: target,
+  routes: [localRoute(target)],
 });
 
 bridge.registerJsonIntentHandler(target, async (intent) => ({
@@ -94,11 +92,32 @@ bridge.registerJsonIntentHandler(target, async (intent) => ({
   echo: intent.payload,
 }));
 
-registerElectronIntentIpcHandler(ipcMain, bridge);
+// app.whenReady() has resolved. These are your application's absolute paths.
+const window = new BrowserWindow({
+  webPreferences: {
+    preload: bundledPreloadPath,
+    contextIsolation: true,
+    nodeIntegration: false,
+    sandbox: true,
+  },
+});
+const trustedUrl = pathToFileURL(rendererHtmlPath).href;
+const unregister = registerElectronIntentIpcHandler(ipcMain, bridge, {
+  authorize: (event) => event.sender === window.webContents &&
+    event.senderFrame === window.webContents.mainFrame &&
+    event.senderFrame.url === trustedUrl,
+});
+await window.loadFile(rendererHtmlPath);
+// At application shutdown: unregister(), then await bridge.close().
 ```
 
 ## Preload
 
+Bundle this application-owned source into one CommonJS preload file, leaving
+only `electron` external. A sandboxed preload cannot load arbitrary package
+files with `require`; do not disable the sandbox to make package imports work.
+Use that bundled file as `bundledPreloadPath` above.
+
 ```js
 const { contextBridge, ipcRenderer } = require("electron");
 const { createCoAkkaPreloadApi } = require("coakka-v2-connector-electron/preload");
@@ -124,42 +143,62 @@ const result = await window.coakka.intent({
 });
 ```
 
-## Smoke
-
-```sh
-npm run build
-bash scripts/smoke-packaged-package.sh
-```
-
-The packaged smoke installs the generated package into a disposable Electron
-app, loads a hidden renderer window, sends one renderer intent through preload
-and IPC, and verifies that the main process handles it through the runtime host
-exposed by its packaged Node connector dependency.
-
-Package metadata records the exact native generation, release channel, and
-supported platform tuple. Contact: `gabrielgun1983@gmail.com`.
+## Lifecycle And Admission
+
+For sustained renderer traffic, `intentBatch([...])` amortizes a structured-clone
+IPC round trip. Items execute sequentially through the same runtime ask path
+and preserve order. The default maximum is the accepted queue capacity capped
+at 64 intents; an explicit maximum cannot exceed that capacity or 256. A batch
+is not atomic: earlier items remain completed if a later item fails, and later
+items are not started. Prefer single intents for individual completion latency.
+
+The application must authorize every single and batch IPC invocation. Only an
+explicit `true` permits delivery; exceptions and every other value reject the
+invocation. Match the expected window, main frame and trusted document, not
+just a renderer-supplied source name. Remove IPC handlers when their owner
+closes. Do not expose `ipcRenderer` itself through the context bridge.
+
+Startup options are submitted to the native runtime; use
+`runtimeStartupConfig()` for accepted configuration rather than reconstructing
+it from input. Omitted policy uses `AUTO` and `MULTIPLEXED`. Main owns handlers
+and runtime lifetime; a refused duplicate registration leaves the accepted
+handler intact. Await `close()` to retire native ownership and registered
+callbacks; a reader waiting for handler capacity is also awakened. Close does
+not cancel or join already-running application handlers. Their late results
+cannot submit native replies after close begins. Cancel/join application tasks
+separately before releasing resources those tasks still use.
+File and Stream Lane owners must also be explicitly closed by their owners.
+
+Electron inherits the Node package's lazy bounded ask scheduler in the main
+process. It requires no host worker-pool tuning and does not allocate one worker
+per ask. The Electron wrapper adds no second scheduler or response matcher;
+Core still owns ticket matching, timeout/cancellation and completion notifications.
+
+Read the bundled `CONSUMING.md` for preload and renderer setup. The
+[current package ledger](https://github.com/phuong-tran/coakka-samples/blob/main/docs/common/current-packages.md)
+records registry availability.
 
 ## File Lane
 
 The Node dependency exposes `FileLane` to trusted Electron main-process code.
 Do not forward raw file paths, authorization tokens, or lane methods through
-preload/renderer IPC. See the shared [file-lane contract](https://github.com/phuong-tran/coakka-samples/blob/main/docs/runtime-file-transfer.md).
+preload/renderer IPC. See the shared [file-lane contract](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/guides/runtime-file-transfer.md).
 
 ## Stream Lane
 
-Version `2.5.3` contains owner-aware File and Stream Lane connector surfaces for Electron main
-over exact native generation `2.5.1+26f7944de4a4e0598845a54e4775f9463a9e33be`. Keep runtime ownership in the
-main process and follow the public
-[streaming contract](https://github.com/phuong-tran/coakka-samples/blob/main/docs/runtime-streaming.md).
+The matching Node dependency provides owner-aware File and Stream Lane surfaces
+for trusted Electron main-process code. Keep runtime ownership in the main
+process and follow the public
+[streaming contract](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/guides/runtime-streaming.md).
 Electron re-exports Node's `FileReceiveGrant`, `StreamPublishGrant`, and
 `openOwned`/`prepare*Grant` methods only to main-process code. Follow the
-[owner-grant ONE/ALL sample](https://github.com/phuong-tran/coakka-samples/blob/main/docs/runtime-lane-owner-grants.md)
+[owner-grant ONE/ALL sample](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/reference/runtime-lane-owner-grants.md)
 and keep serialized grants out of preload and renderer IPC.
 
 ## AI-Assisted Integration
 
 Before generating Electron integration code, read the public
-[AI-assisted integration guide](https://github.com/phuong-tran/coakka-samples/blob/main/docs/ai-assisted-integration.md)
+[AI-assisted integration guide](https://github.com/phuong-tran/coakka-samples/blob/main/docs/coakka-runtime/guides/ai-assisted-integration.md)
 and the runnable Electron sample. Connection policy and native lane ownership
 belong to Electron main; renderer code sends validated intent only.
 
@@ -170,11 +209,11 @@ belong to Electron main; renderer code sends validated intent only.
 
 Connector source, generated bindings, type declarations, examples, and package
 documentation use the [Apache License, Version 2.0](https://github.com/phuong-tran/coakka-samples/blob/main/LICENSE).
-Bundled Native Core files use the [CoAkka Native Artifact License 1.2](https://github.com/phuong-tran/coakka-samples/blob/main/NATIVE-LICENSE.md).
+Native Core files in the Node dependency use the [CoAkka Native Artifact License 1.2](https://github.com/phuong-tran/coakka-samples/blob/main/NATIVE-LICENSE.md).
 Those native terms permit ordinary application and SaaS use but require a
 separate agreement to sell or offer CoAkka itself as managed runtime or
 infrastructure.
 
-See [CoAkka Package Licensing](https://github.com/phuong-tran/coakka-samples/blob/main/docs/package-licensing.md)
+See [CoAkka Package Licensing](https://github.com/phuong-tran/coakka-samples/blob/main/docs/common/package-licensing.md)
 for the file-scope map. The package also carries offline `LICENSE`,
 `NATIVE-LICENSE.md`, `PACKAGE-LICENSE.md`, and `NOTICE` copies.

package/dist/index.d.ts

@@ -1,13 +1,14 @@
-import { type RuntimeCapabilitiesSnapshot, type RuntimeTcpConnectionApplyResult, type RuntimeTcpConnectionConfigSnapshot, type RuntimeTcpConnectionStrategySpec, type RuntimeTcpSecurityApplyResult, type RuntimeTcpSecurityInfoSnapshot, type RuntimeTcpSecuritySpec } from "coakka-v2-connector-node";
-export { RuntimeCapability, RuntimeTcpConnectionMode, RuntimeTcpSecurityMode, RuntimeTlsReloadMode, supportsRuntimeCapabilities, } from "coakka-v2-connector-node";
+import { type ConnectorStartSpec, type RuntimeClientStats, type RuntimeCapabilitiesSnapshot, type RuntimeDeliverySnapshot, type RuntimeInfoSnapshot, type RuntimeStartupSnapshot, type RuntimeTcpConnectionApplyResult, type RuntimeTcpConnectionConfigSnapshot, type RuntimeTcpConnectionStrategySpec, type RuntimeTcpSecurityApplyResult, type RuntimeTcpSecurityInfoSnapshot, type RuntimeTcpSecuritySpec } from "coakka-v2-connector-node";
+export { EndpointFlag, RuntimeCapability, RuntimeNetworkMode, RuntimeTcpConnectionMode, RuntimeTcpSecurityMode, RuntimeTlsReloadMode, RouteStrategy, embeddedNetwork, localRoute, networkNode, outboundOnlyNetwork, supportsRuntimeCapabilities, type EndpointSpec, type RouteSpec, type RuntimeNetworkConfig, } from "coakka-v2-connector-node";
 /**
  * File and Stream Lanes are available only to trusted Electron main-process
  * code. They are intentionally absent from preload and renderer intents so
  * file paths and bearer grants never cross that boundary implicitly.
  */
 export { FILE_LANE_DETAIL_MAX_BYTES, FILE_LANE_SHA256_BYTES, LANE_OWNER_GRANTS_FEATURE, FileLane, FileLaneError, FileLaneFlag, FileLaneSecurityMode, FileReceiveGrant, FileTransferDirection, FileTransferResult, FileTransferState, LaneOwnerGrantUnavailableError, STREAM_LANE_DETAIL_MAX_BYTES, STREAM_LANE_MAX_FRAME_BYTES, STREAM_LANE_MAX_WINDOW_BYTES, StreamConsumerDecision, StreamDirection, StreamFrameFlag, StreamLane, StreamLaneError, StreamLaneFlag, StreamLaneSecurityMode, StreamPublishGrant, StreamPressureReason, StreamPressureState, StreamResult, StreamSourceSignal, StreamState, type FileDigest, type FileLaneConfig, type FileLaneSecurityConfig, type FileLaneStats, type FileReceiveSpec, type FileSendSpec, type FileTransferSnapshot, type LaneOwnerConfig, type LaneOwnerEndpoint, type StreamConsumer, type StreamFrameMetadata, type StreamLaneConfig, type StreamLaneSecurityConfig, type StreamLaneStats, type StreamPressureSnapshot, type StreamPublishSpec, type StreamSessionSnapshot, type StreamSource, type StreamSourceFrame, type StreamSubscribeSpec, } from "coakka-v2-connector-node";
-export declare const COAKKA_ELECTRON_CONNECTOR_VERSION = "2.5.3";
+export declare const COAKKA_ELECTRON_CONNECTOR_VERSION = "3.1.1";
 export declare const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
+export declare const COAKKA_ELECTRON_INTENT_BATCH_CHANNEL = "coakka:intent-batch";
 export interface ElectronIntentPayloadIdentity {
     messageType: string;
     payloadSchemaVersion?: number;
@@ -29,47 +30,50 @@ export interface ElectronIntentResult {
     target: string;
     operation: string;
     payload: Record<string, unknown>;
-    runtime: {
-        generation: number;
-        delivered: number;
-        matchedResponses: number;
-        matchedDeadletters: number;
+    payloadIdentity: {
+        messageType: string;
+        payloadSchemaVersion: number;
+        payloadFormat: "json";
     };
 }
-export interface ElectronRuntimeIntentBridgeOptions {
-    systemName: string;
-    nodeId: string;
-    defaultTarget: string;
-    routePort?: number;
-    queueCapacity?: number;
-    strictNoDrop?: boolean;
+export interface ElectronRuntimeIntentBridgeOptions extends ConnectorStartSpec {
     runtimeLibPath?: string;
-    connectionStrategy?: RuntimeTcpConnectionStrategySpec;
-    security?: RuntimeTcpSecuritySpec;
 }
 export type ElectronJsonIntentHandler = (intent: ElectronIntentEnvelope) => Record<string, unknown> | Promise<Record<string, unknown>>;
 export interface IpcMainLike {
-    handle(channel: string, listener: (event: unknown, intent: ElectronIntentEnvelope) => Promise<ElectronIntentResult>): void;
+    handle(channel: string, listener: (event: unknown, payload: unknown) => Promise<unknown>): void;
     removeHandler(channel: string): void;
 }
+export interface ElectronIntentIpcRegistrationOptions {
+    channel?: string;
+    batchChannel?: string;
+    /** Defaults to Core's accepted queue capacity, capped at 64 IPC values. */
+    maximumBatchSize?: number;
+    /** App-owned sender/frame trust decision; only literal true permits dispatch. */
+    authorize(event: unknown): boolean | Promise<boolean>;
+}
 export declare class ElectronRuntimeIntentBridge {
     private readonly runtimeHost;
-    readonly defaultTarget: string;
     static start(options: ElectronRuntimeIntentBridgeOptions): ElectronRuntimeIntentBridge;
     private readonly handlers;
     private closed;
+    private closePromise;
     private constructor();
     registerJsonIntentHandler(target: string, handler: ElectronJsonIntentHandler): void;
     handleIntent(intent: ElectronIntentEnvelope): Promise<ElectronIntentResult>;
+    runtimeInfo(): RuntimeInfoSnapshot;
+    /** Connector-owned counters for trusted main-process diagnostics only. */
+    connectorStats(): RuntimeClientStats;
+    runtimeStartupConfig(): RuntimeStartupSnapshot & {
+        delivery: RuntimeDeliverySnapshot;
+    };
     runtimeCapabilities(): RuntimeCapabilitiesSnapshot;
     tcpConnectionConfig(): RuntimeTcpConnectionConfigSnapshot;
     tcpSecurityInfo(): RuntimeTcpSecurityInfoSnapshot;
-    startupConnectionResult(): RuntimeTcpConnectionApplyResult | null;
-    startupSecurityResult(): RuntimeTcpSecurityApplyResult | null;
     applyTcpConnectionStrategy(spec: RuntimeTcpConnectionStrategySpec): RuntimeTcpConnectionApplyResult;
     applyTcpSecurity(spec: RuntimeTcpSecuritySpec): RuntimeTcpSecurityApplyResult;
-    close(): void;
+    close(): Promise<void>;
     private createRuntimeHandler;
     private requireOpen;
 }
-export declare function registerElectronIntentIpcHandler(ipcMain: IpcMainLike, bridge: ElectronRuntimeIntentBridge, channel?: string): () => void;
+export declare function registerElectronIntentIpcHandler(ipcMain: IpcMainLike, bridge: ElectronRuntimeIntentBridge, options: ElectronIntentIpcRegistrationOptions): () => void;

package/dist/index.js

@@ -1,191 +1 @@
-import { DeliveryHint, EndpointFlag, NodeRuntimeClient, PayloadFormat, PayloadIdentity, RuntimeHost, } from "coakka-v2-connector-node";
-export { RuntimeCapability, RuntimeTcpConnectionMode, RuntimeTcpSecurityMode, RuntimeTlsReloadMode, supportsRuntimeCapabilities, } from "coakka-v2-connector-node";
-/**
- * File and Stream Lanes are available only to trusted Electron main-process
- * code. They are intentionally absent from preload and renderer intents so
- * file paths and bearer grants never cross that boundary implicitly.
- */
-export { FILE_LANE_DETAIL_MAX_BYTES, FILE_LANE_SHA256_BYTES, LANE_OWNER_GRANTS_FEATURE, FileLane, FileLaneError, FileLaneFlag, FileLaneSecurityMode, FileReceiveGrant, FileTransferDirection, FileTransferResult, FileTransferState, LaneOwnerGrantUnavailableError, STREAM_LANE_DETAIL_MAX_BYTES, STREAM_LANE_MAX_FRAME_BYTES, STREAM_LANE_MAX_WINDOW_BYTES, StreamConsumerDecision, StreamDirection, StreamFrameFlag, StreamLane, StreamLaneError, StreamLaneFlag, StreamLaneSecurityMode, StreamPublishGrant, StreamPressureReason, StreamPressureState, StreamResult, StreamSourceSignal, StreamState, } from "coakka-v2-connector-node";
-export const COAKKA_ELECTRON_CONNECTOR_VERSION = "2.5.3";
-export const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
-const DEFAULT_ROUTE_PORT = 19481;
-export class ElectronRuntimeIntentBridge {
-    runtimeHost;
-    defaultTarget;
-    static start(options) {
-        const target = requireNonBlank(options.defaultTarget, "defaultTarget");
-        const startSpec = {
-            systemName: requireNonBlank(options.systemName, "systemName"),
-            nodeId: requireNonBlank(options.nodeId, "nodeId"),
-            queueCapacity: options.queueCapacity ?? 64,
-            strictNoDrop: options.strictNoDrop ?? true,
-            generation: 1,
-            connectionStrategy: options.connectionStrategy,
-            security: options.security,
-            routes: [
-                {
-                    target,
-                    endpoints: [
-                        {
-                            host: "127.0.0.1",
-                            port: options.routePort ?? DEFAULT_ROUTE_PORT,
-                            flags: EndpointFlag.LOCAL,
-                        },
-                    ],
-                },
-            ],
-        };
-        return new ElectronRuntimeIntentBridge(RuntimeHost.start(startSpec, options.runtimeLibPath), target);
-    }
-    handlers = new Map();
-    closed = false;
-    constructor(runtimeHost, defaultTarget) {
-        this.runtimeHost = runtimeHost;
-        this.defaultTarget = defaultTarget;
-    }
-    registerJsonIntentHandler(target, handler) {
-        const normalizedTarget = requireNonBlank(target, "target");
-        this.handlers.set(normalizedTarget, handler);
-        this.runtimeHost.registerHandler(normalizedTarget, this.createRuntimeHandler(normalizedTarget), true);
-    }
-    async handleIntent(intent) {
-        this.requireOpen();
-        const normalized = normalizeIntent(intent);
-        const identity = toPayloadIdentity(normalized.payloadIdentity);
-        const response = await this.runtimeHost.askJson(normalized.source, normalized.target, normalized.payload, identity, normalized.timeoutMs ?? 2_000, normalized.operation, DeliveryHint.ROUTER_DEFAULT, normalized.headers ?? {});
-        const clientStats = this.runtimeHost.clientStats();
-        const runtimeStats = this.runtimeHost.stats();
-        return {
-            intentId: normalized.intentId,
-            source: normalized.source,
-            target: normalized.target,
-            operation: normalized.operation,
-            payload: response,
-            runtime: {
-                generation: runtimeStats.appliedGeneration,
-                delivered: clientStats.deliveredRequests,
-                matchedResponses: clientStats.matchedResponses,
-                matchedDeadletters: clientStats.matchedDeadletters,
-            },
-        };
-    }
-    runtimeCapabilities() {
-        return this.runtimeHost.runtimeCapabilities();
-    }
-    tcpConnectionConfig() {
-        return this.runtimeHost.tcpConnectionConfig();
-    }
-    tcpSecurityInfo() {
-        return this.runtimeHost.tcpSecurityInfo();
-    }
-    startupConnectionResult() {
-        return this.runtimeHost.startupConnectionResult();
-    }
-    startupSecurityResult() {
-        return this.runtimeHost.startupSecurityResult();
-    }
-    applyTcpConnectionStrategy(spec) {
-        return this.runtimeHost.applyTcpConnectionStrategy(spec);
-    }
-    applyTcpSecurity(spec) {
-        return this.runtimeHost.applyTcpSecurity(spec);
-    }
-    close() {
-        if (this.closed) {
-            return;
-        }
-        this.closed = true;
-        this.runtimeHost.close();
-    }
-    createRuntimeHandler(target) {
-        return async (request) => {
-            const handler = this.handlers.get(target);
-            if (handler == null) {
-                throw new Error(`no Electron intent handler registered for target=${target}`);
-            }
-            const payload = JSON.parse(Buffer.from(request.payload).toString("utf8"));
-            const resultPayload = await handler({
-                intentId: request.message_id,
-                source: request.source,
-                target,
-                operation: "intent",
-                payload,
-                payloadIdentity: {
-                    messageType: request.message_type,
-                    payloadSchemaVersion: request.payload_schema_version,
-                    payloadFormat: "json",
-                },
-                headers: request.headers,
-            });
-            return NodeRuntimeClient.makeJsonReplyFromRequestIdentity(request, target, resultPayload);
-        };
-    }
-    requireOpen() {
-        if (this.closed) {
-            throw new Error("Electron runtime intent bridge is closed");
-        }
-    }
-}
-export function registerElectronIntentIpcHandler(ipcMain, bridge, channel = COAKKA_ELECTRON_INTENT_CHANNEL) {
-    ipcMain.handle(channel, async (_event, intent) => bridge.handleIntent(intent));
-    return () => ipcMain.removeHandler(channel);
-}
-function normalizeIntent(intent) {
-    if (intent == null || typeof intent !== "object") {
-        throw new Error("intent envelope is required");
-    }
-    return {
-        intentId: requireNonBlank(intent.intentId, "intentId"),
-        source: requireNonBlank(intent.source, "source"),
-        target: requireNonBlank(intent.target, "target"),
-        operation: requireNonBlank(intent.operation, "operation"),
-        payload: requireJsonObject(intent.payload, "payload"),
-        payloadIdentity: requirePayloadIdentity(intent.payloadIdentity),
-        timeoutMs: normalizeTimeout(intent.timeoutMs),
-        headers: normalizeHeaders(intent.headers),
-    };
-}
-function toPayloadIdentity(identity) {
-    return new PayloadIdentity(identity.messageType, identity.payloadSchemaVersion ?? 1, PayloadFormat.JSON).requireTyped("Electron intent payloadIdentity");
-}
-function requirePayloadIdentity(identity) {
-    if (identity == null || typeof identity !== "object") {
-        throw new Error("payloadIdentity is required");
-    }
-    return {
-        messageType: requireNonBlank(identity.messageType, "payloadIdentity.messageType"),
-        payloadSchemaVersion: identity.payloadSchemaVersion ?? 1,
-        payloadFormat: "json",
-    };
-}
-function requireJsonObject(value, what) {
-    if (value == null || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`${what} must be a JSON object`);
-    }
-    return value;
-}
-function normalizeHeaders(headers) {
-    if (headers == null) {
-        return {};
-    }
-    const normalized = {};
-    for (const [key, value] of Object.entries(headers)) {
-        normalized[requireNonBlank(key, "header key")] = String(value);
-    }
-    return normalized;
-}
-function normalizeTimeout(timeoutMs) {
-    if (timeoutMs == null) {
-        return undefined;
-    }
-    if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
-        throw new Error("timeoutMs must be a positive integer");
-    }
-    return timeoutMs;
-}
-function requireNonBlank(value, what) {
-    if (typeof value !== "string" || value.trim() === "") {
-        throw new Error(`${what} is required`);
-    }
-    return value;
-}
+var S=Object.defineProperty;var a=(e,t)=>S(e,"name",{value:t,configurable:!0});import{DeliveryHint as w,NodeRuntimeClient as T,PayloadFormat as y,PayloadIdentity as f,RuntimeHost as I}from"coakka-v2-connector-node";import{EndpointFlag as z,RuntimeCapability as j,RuntimeNetworkMode as k,RuntimeTcpConnectionMode as B,RuntimeTcpSecurityMode as x,RuntimeTlsReloadMode as D,RouteStrategy as J,embeddedNetwork as V,localRoute as $,networkNode as v,outboundOnlyNetwork as K,supportsRuntimeCapabilities as U}from"coakka-v2-connector-node";import{FILE_LANE_DETAIL_MAX_BYTES as Y,FILE_LANE_SHA256_BYTES as G,LANE_OWNER_GRANTS_FEATURE as W,FileLane as Q,FileLaneError as Z,FileLaneFlag as ee,FileLaneSecurityMode as te,FileReceiveGrant as re,FileTransferDirection as ne,FileTransferResult as oe,FileTransferState as ae,LaneOwnerGrantUnavailableError as ie,STREAM_LANE_DETAIL_MAX_BYTES as se,STREAM_LANE_MAX_FRAME_BYTES as ue,STREAM_LANE_MAX_WINDOW_BYTES as le,StreamConsumerDecision as ce,StreamDirection as me,StreamFrameFlag as de,StreamLane as pe,StreamLaneError as he,StreamLaneFlag as ye,StreamLaneSecurityMode as fe,StreamPublishGrant as Ee,StreamPressureReason as Se,StreamPressureState as we,StreamResult as Te,StreamSourceSignal as Ie,StreamState as ge}from"coakka-v2-connector-node";var L="3.1.1",g="coakka:intent",_="coakka:intent-batch",C=2e3,p=3e4,h=class e{static{a(this,"ElectronRuntimeIntentBridge")}runtimeHost;static start(t){let{runtimeLibPath:r,...n}=t;return new e(I.start(n,r))}handlers=new Map;closed=!1;closePromise=null;constructor(t){this.runtimeHost=t}registerJsonIntentHandler(t,r){this.requireOpen();let n=i(t,"target");if(typeof r!="function")throw new TypeError("Electron intent handler must be a function");this.runtimeHost.registerHandler(n,this.createRuntimeHandler(n),!0),this.handlers.set(n,r)}async handleIntent(t){this.requireOpen();let r=N(t),n=O(r.payloadIdentity),o=await this.runtimeHost.askTyped(r.source,r.target,Buffer.from(JSON.stringify(r.payload)),n,r.timeoutMs??C,r.operation,w.ROUTER_DEFAULT,r.headers??{}),s=new f(o.message_type,o.payload_schema_version,o.payload_format).requireTyped("Electron intent response");if(s.payloadFormat!==y.JSON)throw new Error("Electron intent response payloadFormat must be json");let u=m(JSON.parse(Buffer.from(o.payload).toString("utf8")),"response payload");return{intentId:r.intentId,source:r.source,target:r.target,operation:r.operation,payload:u,payloadIdentity:{messageType:s.messageType,payloadSchemaVersion:s.payloadSchemaVersion,payloadFormat:"json"}}}runtimeInfo(){return this.requireOpen(),this.runtimeHost.runtimeInfo()}connectorStats(){return this.requireOpen(),this.runtimeHost.clientStats()}runtimeStartupConfig(){return this.requireOpen(),this.runtimeHost.runtimeStartupConfig()}runtimeCapabilities(){return this.requireOpen(),this.runtimeHost.runtimeCapabilities()}tcpConnectionConfig(){return this.requireOpen(),this.runtimeHost.tcpConnectionConfig()}tcpSecurityInfo(){return this.requireOpen(),this.runtimeHost.tcpSecurityInfo()}applyTcpConnectionStrategy(t){return this.requireOpen(),this.runtimeHost.applyTcpConnectionStrategy(t)}applyTcpSecurity(t){return this.requireOpen(),this.runtimeHost.applyTcpSecurity(t)}close(){return this.closePromise!=null?this.closePromise:(this.closed=!0,this.handlers.clear(),this.closePromise=this.runtimeHost.close(),this.closePromise)}createRuntimeHandler(t){return async r=>{let n=this.handlers.get(t);if(n==null)throw new Error(`no Electron intent handler registered for target=${t}`);let o=m(JSON.parse(Buffer.from(r.payload).toString("utf8")),"request payload"),s=await n({intentId:r.message_id,source:r.source,target:t,operation:i(r.headers.operation,"request operation"),payload:o,payloadIdentity:{messageType:r.message_type,payloadSchemaVersion:r.payload_schema_version,payloadFormat:"json"},headers:r.headers});return T.makeJsonReplyFromRequestIdentity(r,t,m(s,"handler response payload"))}}requireOpen(){if(this.closed)throw new Error("Electron runtime intent bridge is closed")}};function P(e,t,r){let n=i(r.channel??g,"IPC channel"),o=i(r.batchChannel??_,"IPC batch channel");if(n===o)throw new Error("Electron intent and batch IPC channels must be distinct");if(typeof r.authorize!="function")throw new Error("Electron intent IPC registration requires an authorize policy");let s=t.runtimeStartupConfig().queueCapacity,u=r.maximumBatchSize??Math.min(s,64);if(!Number.isInteger(u)||u<1||u>s||u>256)throw new Error(`maximumBatchSize must be an integer in 1..${Math.min(s,256)}`);e.handle(n,async(c,l)=>{if(await r.authorize(c)!==!0)throw new Error("Electron intent IPC sender is not authorized");return t.handleIntent(l)});try{e.handle(o,async(c,l)=>{if(await r.authorize(c)!==!0)throw new Error("Electron intent IPC sender is not authorized");if(!Array.isArray(l)||l.length<1||l.length>u)throw new Error(`Electron intent batch must contain 1..${u} intents`);let d=[];for(let E of l)d.push(await t.handleIntent(E));return d})}catch(c){throw e.removeHandler(n),c}return()=>{e.removeHandler(n),e.removeHandler(o)}}a(P,"registerElectronIntentIpcHandler");function N(e){if(e==null||typeof e!="object")throw new Error("intent envelope is required");return{intentId:i(e.intentId,"intentId"),source:i(e.source,"source"),target:i(e.target,"target"),operation:i(e.operation,"operation"),payload:m(e.payload,"payload"),payloadIdentity:A(e.payloadIdentity),timeoutMs:R(e.timeoutMs),headers:b(e.headers)}}a(N,"normalizeIntent");function O(e){return new f(e.messageType,e.payloadSchemaVersion??1,y.JSON).requireTyped("Electron intent payloadIdentity")}a(O,"toPayloadIdentity");function A(e){if(e==null||typeof e!="object")throw new Error("payloadIdentity is required");if(e.payloadFormat!=null&&e.payloadFormat!=="json")throw new Error("payloadIdentity.payloadFormat must be json");let t=e.payloadSchemaVersion??1;if(!Number.isInteger(t)||t<1||t>4294967295)throw new Error("payloadIdentity.payloadSchemaVersion must be an integer in 1..4294967295");return{messageType:i(e.messageType,"payloadIdentity.messageType"),payloadSchemaVersion:t,payloadFormat:"json"}}a(A,"requirePayloadIdentity");function m(e,t){if(e==null||typeof e!="object"||Array.isArray(e))throw new Error(`${t} must be a JSON object`);return e}a(m,"requireJsonObject");function b(e){if(e==null)return{};let t=Object.create(null);for(let[r,n]of Object.entries(e)){let o=i(r,"header key");if(["method","operation"].includes(o.toLowerCase()))throw new Error(`headers.${o} is reserved by the intent envelope`);if(typeof n!="string")throw new Error(`headers.${o} must be a string`);t[o]=n}return t}a(b,"normalizeHeaders");function R(e){if(e!=null){if(!Number.isInteger(e)||e<1||e>p)throw new Error(`timeoutMs must be an integer in 1..${p}`);return e}}a(R,"normalizeTimeout");function i(e,t){if(typeof e!="string"||e.trim()==="")throw new Error(`${t} is required`);return e}a(i,"requireNonBlank");export{L as COAKKA_ELECTRON_CONNECTOR_VERSION,_ as COAKKA_ELECTRON_INTENT_BATCH_CHANNEL,g as COAKKA_ELECTRON_INTENT_CHANNEL,h as ElectronRuntimeIntentBridge,z as EndpointFlag,Y as FILE_LANE_DETAIL_MAX_BYTES,G as FILE_LANE_SHA256_BYTES,Q as FileLane,Z as FileLaneError,ee as FileLaneFlag,te as FileLaneSecurityMode,re as FileReceiveGrant,ne as FileTransferDirection,oe as FileTransferResult,ae as FileTransferState,W as LANE_OWNER_GRANTS_FEATURE,ie as LaneOwnerGrantUnavailableError,J as RouteStrategy,j as RuntimeCapability,k as RuntimeNetworkMode,B as RuntimeTcpConnectionMode,x as RuntimeTcpSecurityMode,D as RuntimeTlsReloadMode,se as STREAM_LANE_DETAIL_MAX_BYTES,ue as STREAM_LANE_MAX_FRAME_BYTES,le as STREAM_LANE_MAX_WINDOW_BYTES,ce as StreamConsumerDecision,me as StreamDirection,de as StreamFrameFlag,pe as StreamLane,he as StreamLaneError,ye as StreamLaneFlag,fe as StreamLaneSecurityMode,Se as StreamPressureReason,we as StreamPressureState,Ee as StreamPublishGrant,Te as StreamResult,Ie as StreamSourceSignal,ge as StreamState,V as embeddedNetwork,$ as localRoute,v as networkNode,K as outboundOnlyNetwork,P as registerElectronIntentIpcHandler,U as supportsRuntimeCapabilities};

package/dist/preload.cjs

@@ -1,16 +1 @@
-"use strict";
-
-const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
-
-function createCoAkkaPreloadApi(ipcRenderer, channel = COAKKA_ELECTRON_INTENT_CHANNEL) {
-  return {
-    intent(intent) {
-      return ipcRenderer.invoke(channel, intent);
-    },
-  };
-}
-
-module.exports = {
-  COAKKA_ELECTRON_INTENT_CHANNEL,
-  createCoAkkaPreloadApi,
-};
+"use strict";var o=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var E=(r,t)=>o(r,"name",{value:t,configurable:!0});var C=(r,t)=>{for(var n in t)o(r,n,{get:t[n],enumerable:!0})},u=(r,t,n,e)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of A(t))!k.call(r,i)&&i!==n&&o(r,i,{get:()=>t[i],enumerable:!(e=s(t,i))||e.enumerable});return r};var T=r=>u(o({},"__esModule",{value:!0}),r);var a={};C(a,{COAKKA_ELECTRON_INTENT_BATCH_CHANNEL:()=>N,COAKKA_ELECTRON_INTENT_CHANNEL:()=>c,createCoAkkaPreloadApi:()=>_});module.exports=T(a);var c="coakka:intent",N="coakka:intent-batch";function _(r,t=c,n=N){if(typeof t!="string"||t.trim()==="")throw new Error("Electron intent IPC channel is required");if(typeof n!="string"||n.trim()==="")throw new Error("Electron intent batch IPC channel is required");if(t===n)throw new Error("Electron intent and batch IPC channels must be distinct");return{intent(e){return r.invoke(t,e)},intentBatch(e){return r.invoke(n,e)}}}E(_,"createCoAkkaPreloadApi");0&&(module.exports={COAKKA_ELECTRON_INTENT_BATCH_CHANNEL,COAKKA_ELECTRON_INTENT_CHANNEL,createCoAkkaPreloadApi});

package/dist/preload.d.ts

@@ -1,8 +1,10 @@
 export declare const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
+export declare const COAKKA_ELECTRON_INTENT_BATCH_CHANNEL = "coakka:intent-batch";
 export interface IpcRendererLike {
     invoke(channel: string, payload: unknown): Promise<unknown>;
 }
 export interface CoAkkaElectronPreloadApi {
     intent(intent: unknown): Promise<unknown>;
+    intentBatch(intents: readonly unknown[]): Promise<unknown>;
 }
-export declare function createCoAkkaPreloadApi(ipcRenderer: IpcRendererLike, channel?: string): CoAkkaElectronPreloadApi;
+export declare function createCoAkkaPreloadApi(ipcRenderer: IpcRendererLike, channel?: string, batchChannel?: string): CoAkkaElectronPreloadApi;

package/dist/preload.js

@@ -1,8 +1 @@
-export const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
-export function createCoAkkaPreloadApi(ipcRenderer, channel = COAKKA_ELECTRON_INTENT_CHANNEL) {
-    return {
-        intent(intent) {
-            return ipcRenderer.invoke(channel, intent);
-        },
-    };
-}
+var o=Object.defineProperty;var i=(r,t)=>o(r,"name",{value:t,configurable:!0});var E="coakka:intent",c="coakka:intent-batch";function s(r,t=E,n=c){if(typeof t!="string"||t.trim()==="")throw new Error("Electron intent IPC channel is required");if(typeof n!="string"||n.trim()==="")throw new Error("Electron intent batch IPC channel is required");if(t===n)throw new Error("Electron intent and batch IPC channels must be distinct");return{intent(e){return r.invoke(t,e)},intentBatch(e){return r.invoke(n,e)}}}i(s,"createCoAkkaPreloadApi");export{c as COAKKA_ELECTRON_INTENT_BATCH_CHANNEL,E as COAKKA_ELECTRON_INTENT_CHANNEL,s as createCoAkkaPreloadApi};

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "coakka-v2-connector-electron",
-  "version": "2.5.3",
-  "description": "Electron connector for the polyglot, multi-language, multi-platform CoAkka Runtime ecosystem",
+  "version": "3.1.1",
+  "description": "Electron connector for CoAkka Runtime, a native-backed polyglot distributed runtime for application-owned work",
   "license": "SEE LICENSE IN PACKAGE-LICENSE.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/phuong-tran/coakka-publish.git"
   },
-  "homepage": "https://github.com/phuong-tran/coakka-samples/tree/main/runtime/electron",
+  "homepage": "https://github.com/phuong-tran/coakka-samples/tree/main/docs/coakka-runtime",
   "bugs": {
     "url": "https://github.com/phuong-tran/coakka-samples/issues"
   },
@@ -20,11 +20,13 @@
     "polyglot",
     "multi-language",
     "multi-platform",
-    "ipc"
+    "ipc",
+    "distributed-runtime",
+    "application-owned-work"
   ],
   "type": "module",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.0.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,20 +50,10 @@
     "NOTICE",
     "README.md"
   ],
-  "scripts": {
-    "build": "node scripts/build-package.mjs",
-    "verify": "npm run build",
-    "pack:release": "npm run build && node scripts/pack-release.mjs",
-    "smoke:packaged": "bash scripts/smoke-packaged-package.sh"
-  },
   "dependencies": {
-    "coakka-v2-connector-node": "2.5.3"
+    "coakka-v2-connector-node": "3.1.2"
   },
   "peerDependencies": {
     "electron": ">=42"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.8.3"
   }
 }