arcane-os 0.52.1 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.54.0
+
+- Add `WS` through `arcane-os/websocket-client` and the Node root export,
+  using published `ws-share@3.1.0`. Compatible callers in one loaded module
+  share the exact native socket; `WS.observe()` exposes global lifecycle
+  events and `WS.getConnections()` supplies current connection records.
+  Native per-socket events, complete payloads and `acceptWebSocket` remain
+  unchanged. No automatic reconnect or cross-realm sharing is introduced.
+- Update `event-pubsub` to `6.1.1` and preserve its own `strong-type@2.0.0`
+  browser scope alongside the SDK's existing `strong-type@2.0.1`. Managed
+  maps, installed-package routes and application test contexts carry that
+  scope. Consumers regenerate their normal public SDK projections.
+- Add opt-in `moduleFormat: 'native'` application packaging with operation
+  `outputDirectory`, reachable module graphs, scoped import-map resolution,
+  complete selected assets and external HTMLImport script lifecycle. Correct
+  named-expression lexical scope without changing default import-map output.
+  This is a packaging capability, not a complete browser-extension scaffold.
+- Add `createBrowserDecisionModel` through `arcane-os/ai/browser-decisions`
+  for explicit Laya typed-decisions FP16 and Julia-1 FP32 browser operations.
+  Model activation is lazy and uses the selected upstream Transformers.js
+  runtime; complete inputs/results, ordered batches, lifecycle and cancellation
+  remain observable. No chat-provider replacement, automatic model loading,
+  precision fallback, application default switch or saved-data migration occurs.
+
+## 0.53.0
+
+- Add `acceptWebSocket` through `arcane-os/websocket` and the Node root export.
+  Accept a caller-selected native HTTP/1.1 Upgrade and exchange complete text
+  and binary messages with fragmentation, Ping/Pong, ordered writable
+  backpressure, close/abort handling and observable connection settlement.
+  Buffered Upgrade input reaches synchronously registered listeners in order.
+- Preserve valid text, leading Unicode markers and binary view boundaries.
+  Text that cannot be represented exactly as UTF-8 reports an explicit error
+  before transmission or a close-state change. Browser clients use native
+  `WebSocket`; existing HTTP/TLS listeners, routes and application messages
+  remain caller-owned.
+- No third-party WebSocket runtime, client sharing, reconnect, application
+  envelope, storage, HTTP/2 extended CONNECT or extension negotiation is added.
+  Existing SDK behavior and dependencies remain unchanged. Ordinary consumers
+  update through their public package workflow; optional server integration
+  belongs to the consuming application.
+
 ## 0.52.1
 
 - Preserve an authored host `index.html` at `/` independently of application

package/NOTICE

@@ -7,7 +7,10 @@ informational notice and is not itself a grant of commercial rights.
 
 Third-party material retains its own terms:
 
-- event-pubsub 6.1.0: MIT License; see its installed `licence` file.
+- event-pubsub 6.1.1: MIT License; see browser-runtime/dependencies/event-pubsub/licence.
+- event-pubsub's strong-type 2.0.0 dependency: MIT License; see
+  browser-runtime/dependencies/event-pubsub/dependencies/strong-type/licence.
+- ws-share 3.1.0: DBAD License; see browser-runtime/dependencies/ws-share/licence.md.
 - js-queue 3.1.1: MIT License; see browser-runtime/dependencies/js-queue/licence.md.
 - js-queue's easy-stack 2.1.0 dependency: MIT License; see its installed
   `licence` file. The browser Queue entry does not import this stack module.

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.52.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.54.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/bin/arcane-test.mjs

@@ -115,7 +115,8 @@ async function readManagedImportMapContext(source,signal,testFile){
         protocol:MANAGED_IMPORT_MAP_PROTOCOL,
         boundary:context.boundary,
         baseURL:pathToFileURL(`${canonicalBase}${path.sep}`).href,
-        imports:{...context.imports}
+        imports:{...context.imports},
+        scopes:context.scopes??{}
     };
 }
 

package/browser-runtime/ai/browser-decisions.mjs

@@ -0,0 +1,405 @@
+import Is from '../dependencies/strong-type/index.js';
+import {createArcaneEventSource} from '../event-manager.mjs';
+
+const is = new Is(false);
+const STATE_EVENT = 'ai.decisions.state';
+const DEFAULT_RUNTIME_MODULE = 'https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.3.0/dist/transformers.web.js';
+
+function requiredText(value, name) {
+    if (!is.string(value) || value.length === 0) {
+        throw new TypeError(`${name} must be a nonempty string.`);
+    }
+    return value;
+}
+
+function cancellationReason(signal, message) {
+    if (signal?.reason !== undefined) return signal.reason;
+    const error = new Error(message);
+    error.name = 'AbortError';
+    error.code = 'ARCANE_AI_REQUEST_ABORTED';
+    return error;
+}
+
+function reviveWorkerError(value, seen = new Map()) {
+    if (is.error(value) || value === null || !is.object(value)) return value;
+    if (!is.string(value.name) || !is.string(value.message)) return value;
+    if (seen.has(value)) return seen.get(value);
+    const error = new Error(value.message);
+    seen.set(value, error);
+    for (const key of Object.keys(value)) {
+        let item = value[key];
+        if (key === 'cause') item = reviveWorkerError(item, seen);
+        if (key === 'errors' && is.array(item)) {
+            item = item.map(
+                function reviveNestedError(nested) {
+                    return reviveWorkerError(nested, seen);
+                }
+            );
+        }
+        Object.defineProperty(
+            error,
+            key,
+            {value: item, enumerable: true, configurable: true, writable: true}
+        );
+    }
+    return error;
+}
+
+function createDecisionOperation(op) {
+    const operation = {op};
+    operation.promise = new Promise(
+        function createDecisionOperationPromise(resolve, reject) {
+            operation.resolve = resolve;
+            operation.reject = reject;
+        }
+    );
+    return operation;
+}
+
+/**
+ * One lazily activated model Worker. Cancelling any active operation terminates
+ * that Worker and rejects all of its operations with the same cancellation
+ * reason. A later load/evaluate may activate a fresh Worker after cancellation,
+ * unloading, or failure; disposal is terminal.
+ */
+class BrowserDecisionModel {
+    #configuration;
+    #events;
+    #activation = null;
+    #generation = 0;
+    #nextId = 1;
+    #state = 'unloaded';
+    #progress = null;
+    #error = null;
+    #disposed = false;
+
+    constructor({family, model, revision = 'main', device = 'webgpu', runtime = {}} = {}) {
+        if (family !== 'laya' && family !== 'julia') {
+            throw new TypeError('family must be "laya" or "julia".');
+        }
+        if (runtime === null || !is.object(runtime)) {
+            throw new TypeError('runtime must be an object.');
+        }
+        const moduleUrl = runtime.moduleUrl === undefined
+            ? DEFAULT_RUNTIME_MODULE
+            : runtime.moduleUrl;
+        this.#configuration = {
+            family,
+            model: requiredText(model, 'model'),
+            revision: requiredText(revision, 'revision'),
+            device: requiredText(device, 'device'),
+            dtype: family === 'laya' ? 'fp16' : 'fp32',
+            runtime: {...runtime, moduleUrl: requiredText(moduleUrl, 'runtime.moduleUrl')}
+        };
+        this.#events = createArcaneEventSource(
+            this,
+            {source: 'ai-browser-decisions', eventTypes: [STATE_EVENT]}
+        );
+    }
+
+    status() {
+        const {family, model, revision, device, dtype} = this.#configuration;
+        const activeRequests = this.#activation?.evaluations.size ?? 0;
+        return {
+            family,
+            model,
+            revision,
+            device,
+            dtype,
+            state: this.#state,
+            loaded: this.#state === 'ready',
+            busy: this.#state === 'loading' || activeRequests > 0,
+            activeRequests,
+            progress: this.#progress === null ? null : {...this.#progress},
+            error: this.#error
+        };
+    }
+
+    subscribe(listener, {emitCurrent = true, signal} = {}) {
+        if (!is.function(listener)) throw new TypeError('listener must be a function.');
+        if (!is.boolean(emitCurrent)) throw new TypeError('emitCurrent must be a boolean.');
+        function forwardDecisionState(event) {
+            listener(event.detail);
+        }
+        const unsubscribe = this.#events.on(
+            STATE_EVENT,
+            forwardDecisionState,
+            {signal}
+        );
+        try {
+            if (emitCurrent && !signal?.aborted) {
+                const current = this.status();
+                listener(current);
+            }
+        } catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        return unsubscribe;
+    }
+
+    #publish() {
+        const current = this.status();
+        this.#events.dispatch(STATE_EVENT, current);
+    }
+
+    #assertOperational(signal) {
+        if (this.#disposed) {
+            const error = new Error('The browser decision model is disposed.');
+            error.code = 'ARCANE_AI_DISPOSED';
+            throw error;
+        }
+        if (signal !== undefined && signal !== null
+            && (!is.boolean(signal.aborted)
+                || !is.function(signal.addEventListener)
+                || !is.function(signal.removeEventListener))) {
+            throw new TypeError('signal must be an AbortSignal.');
+        }
+        if (signal?.aborted) {
+            throw cancellationReason(signal, 'The browser decision operation was cancelled.');
+        }
+    }
+
+    #isCurrent(activation) {
+        return this.#activation === activation && this.#generation === activation.generation;
+    }
+
+    #observeSignal(activation, signal) {
+        const model = this;
+        function cancelDecisionActivation() {
+            model.#stop(
+                activation,
+                cancellationReason(signal, 'The browser decision operation was cancelled.'),
+                'unloaded'
+            );
+        }
+        if (signal) {
+            signal.addEventListener(
+                'abort',
+                cancelDecisionActivation,
+                {once: true}
+            );
+            if (signal.aborted) cancelDecisionActivation();
+        }
+        function stopObservingDecisionSignal() {
+            signal?.removeEventListener('abort', cancelDecisionActivation);
+        }
+        return stopObservingDecisionSignal;
+    }
+
+    #activate() {
+        const activation = {
+            generation: ++this.#generation,
+            worker: null,
+            listeners: null,
+            load: createDecisionOperation('load'),
+            pending: new Map(),
+            evaluations: new Set(),
+            reason: undefined
+        };
+        this.#activation = activation;
+        this.#state = 'loading';
+        this.#progress = {phase: 'loading-runtime'};
+        this.#error = null;
+        this.#publish();
+        if (!this.#isCurrent(activation)) return activation;
+        const model = this;
+        try {
+            const worker = new globalThis.Worker(
+                new URL('./decision-worker.mjs', import.meta.url),
+                {type: 'module', name: 'arcane-decisions'}
+            );
+            activation.worker = worker;
+            function handleDecisionWorkerMessage(event) {
+                model.#receive(activation, event.data);
+            }
+            function handleDecisionWorkerError(event) {
+                const error = event.error ?? new Error(
+                    event.message,
+                    {cause: event}
+                );
+                model.#stop(activation, error, 'error');
+            }
+            function handleDecisionWorkerMessageError(event) {
+                const error = new Error(
+                    'The browser could not deserialize the decision worker response.',
+                    {cause: event}
+                );
+                model.#stop(activation, error, 'error');
+            }
+            activation.listeners = {
+                message: handleDecisionWorkerMessage,
+                error: handleDecisionWorkerError,
+                messageerror: handleDecisionWorkerMessageError
+            };
+            for (const [type, listener] of Object.entries(activation.listeners)) {
+                worker.addEventListener(type, listener);
+            }
+            const id = this.#nextId++;
+            activation.pending.set(id, activation.load);
+            worker.postMessage(
+                {id, op: 'load', payload: this.#configuration}
+            );
+        } catch (error) {
+            this.#stop(activation, error, 'error');
+        }
+        return activation;
+    }
+
+    #receive(activation, message) {
+        if (!this.#isCurrent(activation)) return;
+        const operation = message && activation.pending.get(message.id);
+        if (!operation) {
+            this.#stop(
+                activation,
+                new Error(
+                    'The decision worker returned an unknown operation.',
+                    {cause: message}
+                ),
+                'error'
+            );
+            return;
+        }
+        if (Object.hasOwn(message, 'progress')) {
+            this.#progress = message.progress;
+            this.#publish();
+            return;
+        }
+        if (Object.hasOwn(message, 'error')) {
+            const error = reviveWorkerError(message.error);
+            // Transformers.js keeps a Worker-local inference promise chain.
+            // A rejected run can poison that chain; a fresh Worker resets it.
+            this.#stop(activation, error, 'error');
+            return;
+        }
+        if (!Object.hasOwn(message, 'result')) {
+            this.#stop(
+                activation,
+                new Error(
+                    'The decision worker response has no result.',
+                    {cause: message}
+                ),
+                'error'
+            );
+            return;
+        }
+        activation.pending.delete(message.id);
+        if (operation.op === 'load') {
+            this.#state = 'ready';
+            this.#progress = {phase: 'ready'};
+            this.#error = null;
+            this.#publish();
+            if (this.#isCurrent(activation)) {
+                const current = this.status();
+                operation.resolve(current);
+            }
+            return;
+        }
+        operation.resolve(message.result);
+    }
+
+    #stop(activation, reason, state) {
+        if (!this.#isCurrent(activation)) return;
+        activation.reason = reason;
+        this.#activation = null;
+        this.#generation += 1;
+        this.#state = state;
+        this.#progress = null;
+        this.#error = reason;
+        if (activation.worker) {
+            for (const [type, listener] of Object.entries(activation.listeners ?? {})) {
+                activation.worker.removeEventListener(type, listener);
+            }
+            activation.worker.terminate();
+        }
+        activation.load.reject(reason);
+        for (const operation of activation.pending.values()) operation.reject(reason);
+        activation.pending.clear();
+        this.#publish();
+    }
+
+    async load({signal} = {}) {
+        this.#assertOperational(signal);
+        const activation = this.#activation ?? this.#activate();
+        const stopObserving = this.#observeSignal(activation, signal);
+        try {
+            await activation.load.promise;
+            if (!this.#isCurrent(activation)) throw activation.reason;
+            return this.status();
+        } finally {
+            stopObserving();
+        }
+    }
+
+    async evaluate(rows, {signal} = {}) {
+        this.#assertOperational(signal);
+        const activation = this.#activation ?? this.#activate();
+        const evaluation = {};
+        activation.evaluations.add(evaluation);
+        const stopObserving = this.#observeSignal(activation, signal);
+        if (this.#isCurrent(activation)) {
+            this.#progress = {
+                phase: this.#state === 'ready' ? 'evaluating' : 'waiting-for-model'
+            };
+            this.#error = null;
+            this.#publish();
+        }
+        try {
+            await activation.load.promise;
+            if (!this.#isCurrent(activation)) throw activation.reason;
+            const operation = createDecisionOperation('evaluate');
+            const id = this.#nextId++;
+            activation.pending.set(id, operation);
+            try {
+                activation.worker.postMessage(
+                    {id, op: 'evaluate', payload: rows}
+                );
+            } catch (error) {
+                activation.pending.delete(id);
+                this.#error = error;
+                operation.reject(error);
+                this.#publish();
+            }
+            return await operation.promise;
+        } finally {
+            stopObserving();
+            activation.evaluations.delete(evaluation);
+            if (this.#isCurrent(activation)) this.#publish();
+        }
+    }
+
+    unload() {
+        if (this.#disposed) return this.status();
+        const reason = cancellationReason(undefined, 'The browser decision model was unloaded.');
+        if (this.#activation) {
+            this.#stop(this.#activation, reason, 'unloaded');
+        } else {
+            this.#state = 'unloaded';
+            this.#progress = null;
+            this.#error = null;
+            this.#publish();
+        }
+        return this.status();
+    }
+
+    dispose() {
+        if (this.#disposed) return this.status();
+        this.#disposed = true;
+        const reason = cancellationReason(undefined, 'The browser decision model was disposed.');
+        if (this.#activation) {
+            this.#stop(this.#activation, reason, 'disposed');
+        } else {
+            this.#state = 'disposed';
+            this.#progress = null;
+            this.#error = null;
+            this.#publish();
+        }
+        this.#events.dispose();
+        return this.status();
+    }
+}
+
+/** Creates a client without starting a Worker, fetching a runtime, or loading a model. */
+export function createBrowserDecisionModel(configuration) {
+    return new BrowserDecisionModel(configuration);
+}