arcane-os 0.2.2 → 0.3.0

package/runtime/arcane/modules/TerminalClient.js

@@ -1,52 +1,317 @@
+import {createArcaneEventSource} from 'arcane-os/event-manager';
 import TerminalSession from '../entities/TerminalSession.js';
 
+export const TERMINAL_CLIENT_EVENT_TYPES=Object.freeze({
+    sessionStarted:'terminal-session',
+    sessionExited:'terminal-exit',
+    sessionError:'terminal-error',
+    sessionOutput:'terminal-output'
+});
+export const TERMINAL_CLIENT_ERROR_CODES=Object.freeze({
+    capabilityUnavailable:'ARCANE_TERMINAL_CAPABILITY_UNAVAILABLE',
+    disposed:'ARCANE_TERMINAL_CLIENT_DISPOSED',
+    hostEventSubscriptionInvalid:'ARCANE_TERMINAL_HOST_EVENT_SUBSCRIPTION_INVALID',
+    hostEventUnsubscribeRejected:'ARCANE_TERMINAL_HOST_EVENT_UNSUBSCRIBE_REJECTED',
+    eventTypeInvalid:'ARCANE_TERMINAL_CLIENT_EVENT_TYPE_INVALID',
+    staleSessionCleanupRejected:'ARCANE_TERMINAL_STALE_SESSION_CLEANUP_REJECTED',
+    sessionHostError:'ARCANE_TERMINAL_SESSION_HOST_ERROR'
+});
+export const TERMINAL_CLIENT_REASONS=Object.freeze({
+    capabilityUnavailable:'terminal-capability-unavailable',
+    disposed:'terminal-client-disposed',
+    hostEventSubscriptionInvalid:'terminal-host-event-subscription-invalid',
+    hostEventUnsubscribeRejected:'terminal-host-event-unsubscribe-rejected',
+    eventTypeInvalid:'terminal-client-event-type-invalid',
+    staleSessionCleanupRejected:'terminal-stale-session-cleanup-rejected',
+    sessionStarted:'terminal-session-started',
+    sessionExited:'terminal-session-exited',
+    sessionHostErrorReceived:'terminal-session-host-error-received',
+    sessionOutputReceived:'terminal-session-output-received'
+});
+
+function terminalClientError(code,reason,message,cause){
+    const error=cause===undefined
+        ?new Error(message)
+        :new Error(message,{cause});
+    error.code=code;
+    error.reason=reason;
+    return error;
+}
+
+function terminalEventReason(type){
+    if(type==='session')return TERMINAL_CLIENT_REASONS.sessionStarted;
+    if(type==='exit')return TERMINAL_CLIENT_REASONS.sessionExited;
+    if(type==='error')return TERMINAL_CLIENT_REASONS.sessionHostErrorReceived;
+    return TERMINAL_CLIENT_REASONS.sessionOutputReceived;
+}
+
+function terminalPublicDetail(detail,type,reason){
+    const id=detail?.session?.id??detail?.sessionId;
+    const output=typeof detail?.data==='string'?detail.data:'';
+    const code=type==='error'
+        ?typeof detail?.code==='string'&&detail.code
+            ?detail.code
+            :TERMINAL_CLIENT_ERROR_CODES.sessionHostError
+        :null;
+    return Object.freeze({
+        ...(typeof id==='string'&&id?{id}:{}),
+        ...(typeof detail?.stream==='string'?{stream:detail.stream}:{}),
+        ...(output?{byteCount:new TextEncoder().encode(output).byteLength}:{}),
+        ...(typeof detail?.session?.state==='string'?{status:detail.session.state}:{}),
+        ...(code?{code}:{}),
+        reason
+    });
+}
+
 export default class TerminalClient extends EventTarget{
+    #destroyed=false;
+    #events;
+    #generation=0;
+    #operationSequence=0;
     constructor(api=globalThis.Arcane?.terminal){
         super();
         this.api=api||null;
         this.sessions=new Map();
         this.unsubscribe=[];
+        this.#events=createArcaneEventSource(this,{
+            source:'terminal-client',
+            eventTypes:Object.freeze(
+                Object.values(TERMINAL_CLIENT_EVENT_TYPES)
+            )
+        });
         const events=globalThis.Arcane?.events;
         if(events?.on){
-            for(const type of ['terminal.output','terminal.exit','terminal.error']){
-                this.unsubscribe.push(events.on(type,data=>this.receive(type,data)));
+            const client=this;
+            try{
+                for(const type of [
+                    'terminal.output',
+                    'terminal.exit',
+                    'terminal.error'
+                ]){
+                    function receiveTerminalHostEvent(data){
+                        client.receive(type,data);
+                    }
+                    const unsubscribe=events.on(
+                        type,
+                        receiveTerminalHostEvent
+                    );
+                    if(typeof unsubscribe!=='function'
+                        &&typeof unsubscribe?.dispose!=='function'){
+                        throw terminalClientError(
+                            TERMINAL_CLIENT_ERROR_CODES.hostEventSubscriptionInvalid,
+                            TERMINAL_CLIENT_REASONS.hostEventSubscriptionInvalid,
+                            `Arcane.events.on(${type}) must return an unsubscribe function or disposable handle.`
+                        );
+                    }
+                    this.unsubscribe.push(unsubscribe);
+                }
+            }catch(cause){
+                this.#releaseHostSubscriptions();
+                this.#events.dispose();
+                if(cause?.code===TERMINAL_CLIENT_ERROR_CODES.hostEventSubscriptionInvalid){
+                    throw cause;
+                }
+                throw terminalClientError(
+                    TERMINAL_CLIENT_ERROR_CODES.hostEventSubscriptionInvalid,
+                    TERMINAL_CLIENT_REASONS.hostEventSubscriptionInvalid,
+                    'Terminal host event subscription was rejected.',
+                    cause
+                );
             }
         }
     }
 
-    get available(){ return Boolean(this.api?.start&&this.api?.write&&this.api?.close); }
+    addEventListener(type,listener,options){return this.#events.addEventListener(type,listener,options);}
+    removeEventListener(type,listener,options){return this.#events.removeEventListener(type,listener,options);}
+    on(type,listener,options){return this.#events.on(type,listener,options);}
+    subscribe(type,listener,options){return this.#events.subscribe(type,listener,options);}
+    dispatchEvent(value){return this.#events.dispatchEvent(value);}
+
+    get available(){
+        return !this.#destroyed
+            &&Boolean(this.api?.start&&this.api?.write&&this.api?.close);
+    }
+
+    #disposedError(){
+        return terminalClientError(
+            TERMINAL_CLIENT_ERROR_CODES.disposed,
+            TERMINAL_CLIENT_REASONS.disposed,
+            'The terminal client has been disposed.'
+        );
+    }
+
+    #assertOpen(){
+        if(this.#destroyed)throw this.#disposedError();
+    }
+
+    #assertCapability(method){
+        this.#assertOpen();
+        if(typeof this.api?.[method]!=='function'){
+            throw terminalClientError(
+                TERMINAL_CLIENT_ERROR_CODES.capabilityUnavailable,
+                TERMINAL_CLIENT_REASONS.capabilityUnavailable,
+                `The Arcane native terminal ${method} capability is unavailable. Open Terminal from the installed Arcane shell.`
+            );
+        }
+    }
+
+    #assertCurrent(generation){
+        if(this.#destroyed||generation!==this.#generation){
+            throw this.#disposedError();
+        }
+    }
+
+    #releaseHostSubscriptions(){
+        let firstError=null;
+        for(const subscription of this.unsubscribe){
+            try{
+                if(typeof subscription==='function')subscription();
+                else subscription.dispose();
+            }catch(error){
+                firstError??=error;
+            }
+        }
+        this.unsubscribe=[];
+        return firstError;
+    }
 
     async start(options={}){
-        if(!this.available) throw new Error('The Arcane native terminal capability is unavailable. Open Terminal from the installed Arcane shell.');
+        this.#assertCapability('start');
+        const generation=this.#generation;
         const result=await this.api.start(options);
+        if(this.#destroyed||generation!==this.#generation){
+            let cleanupError=null;
+            if(typeof result?.id==='string'&&typeof this.api?.close==='function'){
+                try{
+                    await this.api.close(result.id);
+                }catch(error){
+                    cleanupError=error;
+                }
+            }
+            if(cleanupError){
+                throw terminalClientError(
+                    TERMINAL_CLIENT_ERROR_CODES.staleSessionCleanupRejected,
+                    TERMINAL_CLIENT_REASONS.staleSessionCleanupRejected,
+                    'The terminal client was disposed and cleanup of its newly started host session was rejected.',
+                    cleanupError
+                );
+            }
+            throw this.#disposedError();
+        }
         const session=new TerminalSession({...result,state:'running'});
         this.sessions.set(session.id,session);
         this.emit('session',{session});
         return session;
     }
 
-    async write(id,data){ TerminalSession.id(id);return this.api.write(id,String(data??'')); }
-    async resize(id,columns,rows){ TerminalSession.id(id);return this.api.resize(id,Number(columns),Number(rows)); }
-    async signal(id,signal='interrupt'){ TerminalSession.id(id);return this.api.signal(id,String(signal)); }
+    async write(id,data){
+        this.#assertCapability('write');
+        TerminalSession.id(id);
+        const generation=this.#generation;
+        const result=await this.api.write(id,String(data??''));
+        this.#assertCurrent(generation);
+        return result;
+    }
+
+    async resize(id,columns,rows){
+        this.#assertCapability('resize');
+        TerminalSession.id(id);
+        const generation=this.#generation;
+        const result=await this.api.resize(id,Number(columns),Number(rows));
+        this.#assertCurrent(generation);
+        return result;
+    }
+
+    async signal(id,signal='interrupt'){
+        this.#assertCapability('signal');
+        TerminalSession.id(id);
+        const generation=this.#generation;
+        const result=await this.api.signal(id,String(signal));
+        this.#assertCurrent(generation);
+        return result;
+    }
+
     async close(id){
+        this.#assertCapability('close');
         TerminalSession.id(id);
+        const generation=this.#generation;
         const result=await this.api.close(id);
+        this.#assertCurrent(generation);
         const session=this.sessions.get(id);
         if(session) this.sessions.set(id,session.with({state:'closed'}));
         return result;
     }
 
     receive(type,data={}){
+        if(this.#destroyed)return false;
         const id=String(data.sessionId||'');
-        if(!id||!this.sessions.has(id)) return;
+        if(!id||!this.sessions.has(id))return false;
         if(type==='terminal.exit'){
             const session=this.sessions.get(id).with({state:'exited'});
             this.sessions.set(id,session);
             this.emit('exit',{...data,session});
-        }else if(type==='terminal.error') this.emit('error',data);
-        else this.emit('output',data);
+        }else if(type==='terminal.error'){
+            this.emit('error',data);
+        }else{
+            this.emit('output',data);
+        }
+        return true;
+    }
+
+    emit(type,detail){
+        this.#assertOpen();
+        if(!['session','exit','error','output'].includes(type)){
+            throw terminalClientError(
+                TERMINAL_CLIENT_ERROR_CODES.eventTypeInvalid,
+                TERMINAL_CLIENT_REASONS.eventTypeInvalid,
+                'Terminal client events must be session, exit, error, or output.'
+            );
+        }
+        const eventType=TERMINAL_CLIENT_EVENT_TYPES[
+            type==='session'
+                ?'sessionStarted'
+                :type==='exit'
+                    ?'sessionExited'
+                    :type==='error'
+                        ?'sessionError'
+                        :'sessionOutput'
+        ];
+        const reason=terminalEventReason(type);
+        this.#operationSequence+=1;
+        const operationId=`${this.#events.instanceId}:${type}:${this.#operationSequence.toString(36)}`;
+        const compatibilityDetail=Object.freeze({
+            ...detail,
+            operationId,
+            reason
+        });
+        return this.#events.dispatch(
+            eventType,
+            compatibilityDetail,
+            {
+                operationId,
+                publicDetail:terminalPublicDetail(detail,type,reason)
+            }
+        ).occurrence;
+    }
+
+    destroy(){
+        if(this.#destroyed)return false;
+        this.#destroyed=true;
+        this.#generation+=1;
+        const unsubscribeError=this.#releaseHostSubscriptions();
+        this.#events.dispose();
+        if(unsubscribeError){
+            throw terminalClientError(
+                TERMINAL_CLIENT_ERROR_CODES.hostEventUnsubscribeRejected,
+                TERMINAL_CLIENT_REASONS.hostEventUnsubscribeRejected,
+                'A terminal host event subscription rejected cleanup.',
+                unsubscribeError
+            );
+        }
+        return true;
     }
 
-    emit(type,detail){ this.dispatchEvent(new CustomEvent(`terminal-${type}`,{detail})); }
-    destroy(){ for(const off of this.unsubscribe) if(typeof off==='function') off();this.unsubscribe=[]; }
+    dispose(){
+        return this.destroy();
+    }
 }

package/runtime/arcane/modules/ThemeBootstrap.js

@@ -1,11 +1,83 @@
 import {loadAndApplyTheme} from './ThemeManager.js';
+import {createArcaneEventSource} from 'arcane-os/event-manager';
 
 const sharedKey='arcaneThemeReady';
 const listenerKey='arcaneThemeAppearanceListener';
+const THEME_BOOTSTRAP_EVENT_OWNER=Object.freeze({});
+let themeBootstrapOperationSequence=0;
+const themeBootstrapEvents=createArcaneEventSource(
+    THEME_BOOTSTRAP_EVENT_OWNER,
+    {
+        source:'theme-bootstrap',
+        eventTypes:Object.freeze(['appearance.changed'])
+    }
+);
+
+function installAppearanceListener(ready){
+    const hostEvents=globalThis.Arcane?.events;
+    if(typeof hostEvents?.on!=='function'||globalThis[listenerKey]){
+        return;
+    }
+
+    let active=true;
+    const hostUnsubscribe=hostEvents.on(
+        'appearance.changed',
+        function forwardAppearanceChange(detail={}){
+            themeBootstrapOperationSequence+=1;
+            const forwarded=Object.freeze({
+                scheme:typeof detail?.scheme==='string'?detail.scheme:null,
+                effectiveScheme:typeof detail?.effectiveScheme==='string'
+                    ?detail.effectiveScheme
+                    :null,
+                source:typeof detail?.source==='string'?detail.source:null,
+                reason:'host-appearance-changed'
+            });
+            themeBootstrapEvents.dispatch(
+                'appearance.changed',
+                forwarded,
+                {
+                    operationId:`theme-bootstrap-${themeBootstrapEvents.instanceId}-${themeBootstrapOperationSequence}`,
+                    publicDetail:forwarded
+                }
+            );
+            Promise.resolve(ready).then(function reloadTheme(result){
+                return result?.manager?.load?.();
+            }).catch(function reportThemeReloadFailure(error){
+                console.warn(
+                    '[Arcane theme] Unable to apply the changed host appearance.',
+                    error
+                );
+            });
+        }
+    );
+    const dispose=function disposeArcaneThemeAppearanceListener(){
+        if(!active){
+            return false;
+        }
+        active=false;
+        if(typeof hostUnsubscribe==='function'){
+            hostUnsubscribe();
+        }
+        if(globalThis[listenerKey]===dispose){
+            delete globalThis[listenerKey];
+        }
+        return true;
+    };
+    Object.defineProperty(dispose,'dispose',{
+        value:dispose,
+        enumerable:false,
+        configurable:false,
+        writable:false
+    });
+    globalThis[listenerKey]=dispose;
+}
 
 export function bootstrapArcaneTheme(options={}){
     const useSharedPromise=Object.keys(options).length===0;
-    if(useSharedPromise&&globalThis[sharedKey]) return globalThis[sharedKey];
+    if(useSharedPromise&&globalThis[sharedKey]){
+        installAppearanceListener(globalThis[sharedKey]);
+        return globalThis[sharedKey];
+    }
 
     const ready=loadAndApplyTheme(options).catch(error=>{
         console.warn('[Arcane theme] Unable to load the saved appearance; using the system theme.',error);
@@ -13,14 +85,16 @@ export function bootstrapArcaneTheme(options={}){
     });
 
     if(useSharedPromise) globalThis[sharedKey]=ready;
-    if(useSharedPromise&&globalThis.Arcane?.events?.on&&!globalThis[listenerKey]){
-        globalThis[listenerKey]=globalThis.Arcane.events.on('appearance.changed',async()=>{
-            const result=await ready;
-            if(result?.manager) await result.manager.load();
-        });
+    if(useSharedPromise){
+        installAppearanceListener(ready);
     }
     return ready;
 }
 
+export function disposeArcaneThemeBootstrap(){
+    const dispose=globalThis[listenerKey];
+    return typeof dispose==='function'?dispose():false;
+}
+
 export const arcaneThemeReady=bootstrapArcaneTheme();
 export default arcaneThemeReady;

package/runtime/arcane/modules/ThemeManager.js

@@ -2,6 +2,10 @@ import Theme,{arcaneDarkThemeTokens,arcaneLightThemeTokens} from '../entities/Th
 import PreferenceStore from './PreferenceStore.js';
 import {applyAppearancePreferences,createAppearancePreferenceStore} from './AppearancePreferences.js';
 import SystemAppearance from './SystemAppearance.js';
+import {
+    createArcaneEventSource,
+    projectArcaneDOMEvent
+} from 'arcane-os/event-manager';
 
 const skinSchema=Object.freeze([
     {key:'appearance.activeSkin',type:'text',defaultValue:''},
@@ -9,6 +13,9 @@ const skinSchema=Object.freeze([
 ]);
 
 export default class ThemeManager{
+    #events;
+    #operationSequence=0;
+
     constructor({appearanceStore=null,skinStore=null,systemAppearance=null,root=null}={}){
         this.appearanceStore=appearanceStore||createAppearancePreferenceStore();
         this.skinStore=skinStore||new PreferenceStore({namespace:'arcane',schema:skinSchema});
@@ -17,6 +24,10 @@ export default class ThemeManager{
         this.appearance=this.appearanceStore.defaults();
         this.skinState=this.skinStore.defaults();
         this.customTheme=null;
+        this.#events=createArcaneEventSource(this,{
+            source:'theme-manager',
+            eventTypes:Object.freeze(['arcane-theme-change'])
+        });
     }
 
     async load(){
@@ -53,7 +64,7 @@ export default class ThemeManager{
         ]);
         this.appearance={...this.appearance,'appearance.colorScheme':normalized};
         this.skinState={...this.skinState,'appearance.activeSkin':''};
-        this.apply();await this.syncSystemAppearance();this.emit();
+        this.apply();await this.syncSystemAppearance();this.emit('color-scheme-changed');
         return this.current();
     }
 
@@ -67,7 +78,7 @@ export default class ThemeManager{
         this.customTheme=theme;
         this.skinState={...this.skinState,'appearance.customSkin':JSON.stringify(theme),'appearance.activeSkin':'custom'};
         this.appearance={...this.appearance,'appearance.colorScheme':theme.scheme};
-        this.apply();await this.syncSystemAppearance();this.emit();
+        this.apply();await this.syncSystemAppearance();this.emit('custom-theme-activated');
         return this.current();
     }
 
@@ -80,7 +91,7 @@ export default class ThemeManager{
         ]);
         this.skinState={...this.skinState,'appearance.activeSkin':'custom'};
         this.appearance={...this.appearance,'appearance.colorScheme':this.customTheme.scheme};
-        this.apply();await this.syncSystemAppearance();this.emit();
+        this.apply();await this.syncSystemAppearance();this.emit('custom-theme-activated');
         return this.current();
     }
 
@@ -97,7 +108,7 @@ export default class ThemeManager{
         ]);
         this.customTheme=null;
         this.skinState={...this.skinState,'appearance.customSkin':'','appearance.activeSkin':''};
-        this.apply();await this.syncSystemAppearance();this.emit();
+        this.apply();await this.syncSystemAppearance();this.emit('custom-theme-reset');
         return this.current();
     }
 
@@ -112,10 +123,31 @@ export default class ThemeManager{
         });
     }
 
-    emit(){
-        if(typeof globalThis.CustomEvent==='function'&&typeof globalThis.dispatchEvent==='function'){
-            globalThis.dispatchEvent(new CustomEvent('arcane-theme-change',{detail:this.current()}));
+    emit(reason='theme-state-applied'){
+        const state=this.current();
+        const detail=Object.freeze({...state,reason});
+        this.#operationSequence+=1;
+        const {occurrence}=this.#events.dispatch(
+            'arcane-theme-change',
+            detail,
+            {
+                operationId:`theme-manager-${this.#events.instanceId}-${this.#operationSequence}`,
+                publicDetail:Object.freeze({mode:detail.mode,reason})
+            }
+        );
+        if(typeof globalThis.CustomEvent==='function'
+            &&typeof globalThis.dispatchEvent==='function'){
+            projectArcaneDOMEvent(globalThis,occurrence);
         }
+        return occurrence;
+    }
+
+    dispose(){
+        return this.#events.dispose();
+    }
+
+    destroy(){
+        return this.dispose();
     }
 }