babylonjs-node-particle-editor 9.2.2 → 9.3.1

package/babylon.nodeParticleEditor.d.ts

@@ -2666,7 +2666,69 @@ declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
      * @param options The options for the tool.
      * @returns A token that can be used to dispose of the tool.
      */
-    export function MakeModularTool(options: ModularToolOptions): BABYLON.IDisposable;
+    export function MakeModularTool(options: ModularToolOptions): {
+        dispose: () => Promise<void>;
+    };
+
+
+
+}
+declare namespace BABYLON.NodeParticleEditor {
+
+
+}
+declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
+        /**
+     * Options for creating a modular bridge container.
+     * @experimental
+     * @internal
+     */
+    export type ModularBridgeOptions = {
+        /**
+         * WebSocket port for the bridge's browser port. Defaults to 4400.
+         */
+        port?: number;
+        /**
+         * Session display name reported to the bridge. Defaults to `document.title`.
+         */
+        name?: string;
+        /**
+         * Whether the bridge should automatically start trying to connect.
+         * Defaults to false.
+         */
+        autoStart?: boolean;
+        /**
+         * Additional service definitions to register with the bridge container.
+         */
+        serviceDefinitions?: readonly BABYLON.NodeParticleEditor.SharedUIComponents.WeaklyTypedServiceDefinition[];
+    };
+    /**
+     * A token returned by {@link MakeModularBridge} that owns the headless
+     * {@link BABYLON.NodeParticleEditor.SharedUIComponents.ServiceContainer}. Dispose it to tear down the bridge and all services.
+     * @experimental
+     * @internal
+     */
+    export type ModularBridgeToken = BABYLON.IDisposable & {
+        /**
+         * The headless BABYLON.NodeParticleEditor.SharedUIComponents.ServiceContainer that hosts the bridge.
+         */
+        readonly serviceContainer: BABYLON.NodeParticleEditor.SharedUIComponents.ServiceContainer;
+        /**
+         * Whether this token has been disposed.
+         */
+        readonly isDisposed: boolean;
+    };
+    /**
+     * Creates a headless {@link BABYLON.NodeParticleEditor.SharedUIComponents.ServiceContainer} that hosts a bridge service.
+     *
+     * The returned token owns the container. Dispose it to tear down the bridge.
+     *
+     * @param options Optional configuration for the bridge.
+     * @returns A {@link ModularBridgeToken} that owns the container.
+     * @experimental
+     * @internal
+     */
+    export function MakeModularBridge(options?: ModularBridgeOptions): ModularBridgeToken;
 
 
 
@@ -3186,6 +3248,376 @@ declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
 
 
 
+}
+declare namespace BABYLON.NodeParticleEditor {
+
+
+}
+declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
+        /**
+     * Serializable description of a command argument, used in protocol messages.
+     */
+    export type CommandArgInfo = {
+        /** The name of the argument. */
+        name: string;
+        /** A human-readable description of the argument. */
+        description: string;
+        /** Whether this argument is required. */
+        required?: boolean;
+        /** The type of the argument. Defaults to "string". When "file", the CLI reads the file and sends its contents. */
+        type?: "string" | "file";
+    };
+    /**
+     * Serializable description of a command, used in protocol messages.
+     */
+    export type CommandInfo = {
+        /** A unique identifier for the command. */
+        id: string;
+        /** A human-readable description of the command. */
+        description: string;
+        /** The arguments this command accepts. */
+        args?: CommandArgInfo[];
+    };
+    /**
+     * Serializable description of a session, used in protocol messages.
+     */
+    export type SessionInfo = {
+        /** The numeric session identifier. */
+        id: number;
+        /** The display name of the session. */
+        name: string;
+        /** ISO 8601 timestamp of when the session connected. */
+        connectedAt: string;
+    };
+    /**
+     * CLI → Bridge: Request the list of active browser sessions.
+     */
+    export type SessionsRequest = {
+        /** The message type discriminator. */
+        type: "sessions";
+    };
+    /**
+     * CLI → Bridge: Request the list of commands available from a session.
+     */
+    export type CommandsRequest = {
+        /** The message type discriminator. */
+        type: "commands";
+        /** The session to query for commands. */
+        sessionId: number;
+    };
+    /**
+     * CLI → Bridge: Execute a command on a session.
+     */
+    export type ExecRequest = {
+        /** The message type discriminator. */
+        type: "exec";
+        /** The session to execute the command on. */
+        sessionId: number;
+        /** The identifier of the command to execute. */
+        commandId: string;
+        /** Key-value pairs of arguments for the command. */
+        args: Record<string, string>;
+    };
+    /**
+     * CLI → Bridge: Stop the bridge process.
+     */
+    export type StopRequest = {
+        /** The message type discriminator. */
+        type: "stop";
+    };
+    /**
+     * All messages that the CLI sends to the bridge.
+     */
+    export type CliRequest = SessionsRequest | CommandsRequest | ExecRequest | StopRequest;
+    /**
+     * Bridge → CLI: Response with the list of active sessions.
+     */
+    export type SessionsResponse = {
+        /** The message type discriminator. */
+        type: "sessionsResponse";
+        /** The list of active sessions. */
+        sessions: SessionInfo[];
+    };
+    /**
+     * Bridge → CLI: Response with the list of commands from a session.
+     */
+    export type CommandsResponse = {
+        /** The message type discriminator. */
+        type: "commandsResponse";
+        /** The list of available commands, if successful. */
+        commands?: CommandInfo[];
+        /** An error message, if the request failed. */
+        error?: string;
+    };
+    /**
+     * Bridge → CLI: Response with the result of a command execution.
+     */
+    export type ExecResponse = {
+        /** The message type discriminator. */
+        type: "execResponse";
+        /** The result of the command execution, if successful. */
+        result?: string;
+        /** An error message, if the execution failed. */
+        error?: string;
+    };
+    /**
+     * Bridge → CLI: Acknowledgement that the bridge is stopping.
+     */
+    export type StopResponse = {
+        /** The message type discriminator. */
+        type: "stopResponse";
+        /** Whether the bridge stopped successfully. */
+        success: boolean;
+    };
+    /**
+     * All messages that the bridge sends to the CLI.
+     */
+    export type CliResponse = SessionsResponse | CommandsResponse | ExecResponse | StopResponse;
+    /**
+     * Browser → Bridge: Register a new session.
+     */
+    export type RegisterRequest = {
+        /** The message type discriminator. */
+        type: "register";
+        /** The display name for this session. */
+        name: string;
+    };
+    /**
+     * Browser → Bridge: Response to a listCommands request from the bridge.
+     */
+    export type CommandListResponse = {
+        /** The message type discriminator. */
+        type: "commandListResponse";
+        /** The identifier of the original request. */
+        requestId: string;
+        /** The list of registered commands. */
+        commands: CommandInfo[];
+    };
+    /**
+     * Browser → Bridge: Response to an execCommand request from the bridge.
+     */
+    export type CommandResponse = {
+        /** The message type discriminator. */
+        type: "commandResponse";
+        /** The identifier of the original request. */
+        requestId: string;
+        /** The result of the command execution, if successful. */
+        result?: string;
+        /** An error message, if the execution failed. */
+        error?: string;
+    };
+    /**
+     * Browser → Bridge: Response to a getInfo request from the bridge.
+     */
+    export type InfoResponse = {
+        /** The message type discriminator. */
+        type: "infoResponse";
+        /** The identifier of the original request. */
+        requestId: string;
+        /** The current display name of the session. */
+        name: string;
+    };
+    /**
+     * All messages that the browser sends to the bridge.
+     */
+    export type BrowserRequest = RegisterRequest | CommandListResponse | CommandResponse | InfoResponse;
+    /**
+     * Bridge → Browser: Request the list of registered commands.
+     */
+    export type ListCommandsRequest = {
+        /** The message type discriminator. */
+        type: "listCommands";
+        /** A unique identifier for this request. */
+        requestId: string;
+    };
+    /**
+     * Bridge → Browser: Request execution of a command.
+     */
+    export type ExecCommandRequest = {
+        /** The message type discriminator. */
+        type: "execCommand";
+        /** A unique identifier for this request. */
+        requestId: string;
+        /** The identifier of the command to execute. */
+        commandId: string;
+        /** Key-value pairs of arguments for the command. */
+        args: Record<string, string>;
+    };
+    /**
+     * Bridge → Browser: Request current session information.
+     */
+    export type GetInfoRequest = {
+        /** The message type discriminator. */
+        type: "getInfo";
+        /** A unique identifier for this request. */
+        requestId: string;
+    };
+    /**
+     * All messages that the bridge sends to the browser.
+     */
+    export type BrowserResponse = ListCommandsRequest | ExecCommandRequest | GetInfoRequest;
+
+
+
+}
+declare namespace BABYLON.NodeParticleEditor {
+
+
+}
+declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
+        /**
+     * Options for the CLI bridge service.
+     * @experimental
+     * @internal
+     */
+    export type BridgeServiceOptions = {
+        /**
+         * The WebSocket port for the bridge's browser port.
+         */
+        port: number;
+        /**
+         * The session display name sent to the bridge.
+         * Can be a getter to provide a dynamic value that is re-read
+         * each time the bridge queries session information.
+         */
+        name: string;
+        /**
+         * Whether to automatically start connecting when the service is created.
+         */
+        autoStart: boolean;
+    };
+    /**
+     * Creates the service definition for the CLI Bridge Service.
+     * @param options The options for connecting to the bridge.
+     * @returns A service definition that produces an BABYLON.NodeParticleEditor.SharedUIComponents.IBridgeCommandRegistry and BABYLON.NodeParticleEditor.SharedUIComponents.ICliConnectionStatus.
+     * @experimental
+     * @internal
+     */
+    export function MakeBridgeServiceDefinition(options: BridgeServiceOptions): BABYLON.NodeParticleEditor.SharedUIComponents.ServiceDefinition<[IBridgeCommandRegistry, BABYLON.NodeParticleEditor.SharedUIComponents.ICliConnectionStatus], []>;
+
+
+
+}
+declare namespace BABYLON.NodeParticleEditor {
+
+
+}
+declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
+        /**
+     * The service identity for the CLI connection status.
+     * @experimental
+     * @internal
+     */
+    export var CliConnectionStatusIdentity: unique symbol;
+    /**
+     * Provides the connection status and enable/disable control for the CLI bridge.
+     * @experimental
+     * @internal
+     */
+    export interface ICliConnectionStatus extends BABYLON.NodeParticleEditor.SharedUIComponents.IService<typeof CliConnectionStatusIdentity> {
+        /**
+         * Whether the bridge is enabled. When true, the bridge actively tries to
+         * maintain a WebSocket connection. When false, the bridge is disconnected
+         * and idle.
+         */
+        isEnabled: boolean;
+        /**
+         * Whether the bridge WebSocket is currently connected.
+         */
+        readonly isConnected: boolean;
+        /**
+         * Observable that fires when either {@link isEnabled} or {@link isConnected} changes.
+         */
+        readonly onConnectionStatusChanged: BABYLON.IReadonlyObservable<void>;
+    }
+
+
+
+}
+declare namespace BABYLON.NodeParticleEditor {
+
+
+}
+declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
+        /**
+     * The type of a bridge command argument, which determines how
+     * the CLI processes the value before sending it to the browser.
+     * @experimental
+     * @internal
+     */
+    export type BridgeCommandArgType = "string" | "file";
+    /**
+     * Describes an argument for a bridge command.
+     * @experimental
+     * @internal
+     */
+    export type BridgeCommandArg = {
+        /**
+         * The name of the argument.
+         */
+        name: string;
+        /**
+         * A description of the argument.
+         */
+        description: string;
+        /**
+         * Whether the argument is required.
+         */
+        required?: boolean;
+        /**
+         * The type of the argument. Defaults to "string".
+         * When set to "file", the CLI reads the file at the given path
+         * and passes its contents as the argument value.
+         */
+        type?: BridgeCommandArgType;
+    };
+    /**
+     * Describes a command that can be invoked from the bridge.
+     * @experimental
+     * @internal
+     */
+    export type BridgeCommandDescriptor = {
+        /**
+         * A unique identifier for the command.
+         */
+        id: string;
+        /**
+         * A human-readable description of what the command does.
+         */
+        description: string;
+        /**
+         * The arguments that this command accepts.
+         */
+        args?: BridgeCommandArg[];
+        /**
+         * Executes the command with the given arguments and returns a result string.
+         * @param args A map of argument names to their values.
+         * @returns A promise that resolves to the result string.
+         */
+        executeAsync: (args: Record<string, string>) => Promise<string>;
+    };
+    /**
+     * The service identity for the bridge command registry.
+     * @experimental
+     * @internal
+     */
+    export var BridgeCommandRegistryIdentity: unique symbol;
+    /**
+     * A registry for commands that can be invoked from the bridge.
+     * @experimental
+     * @internal
+     */
+    export interface IBridgeCommandRegistry extends BABYLON.NodeParticleEditor.SharedUIComponents.IService<typeof BridgeCommandRegistryIdentity> {
+        /**
+         * Registers a command that can be invoked from the bridge.
+         * @param descriptor The command descriptor.
+         * @returns A disposable token that unregisters the command when disposed.
+         */
+        addCommand(descriptor: BridgeCommandDescriptor): BABYLON.IDisposable;
+    }
+
+
+
 }
 declare namespace BABYLON.NodeParticleEditor {
 
@@ -3213,14 +3645,13 @@ declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
         [Index in keyof ServiceContracts]: ExtractContractIdentity<ServiceContracts[Index]>;
     };
     type UnionToIntersection<Union> = (Union extends any ? (k: Union) => void : never) extends (k: infer Intersection) => void ? Intersection : never;
-    type MaybePromise<T> = T | Promise<T>;
     /**
      * A factory function responsible for creating a service instance.
      * Consumed services are passed as arguments to the factory function.
-     * The returned value must implement all produced services, and may BABYLON.IDisposable.
-     * If not services are produced, the returned value may implement BABYLON.IDisposable, otherwise it may return void.
+     * The returned value must implement all produced services, and may implement BABYLON.IDisposable.
+     * If no services are produced, the returned value may implement BABYLON.IDisposable, otherwise it may return void.
      */
-    export type ServiceFactory<Produces extends IService<symbol>[], Consumes extends IService<symbol>[]> = (...dependencies: [...Consumes, abortSignal?: AbortSignal]) => MaybePromise<Produces extends [] ? Partial<BABYLON.IDisposable> | void : Partial<BABYLON.IDisposable> & UnionToIntersection<Produces[number]>>;
+    export type ServiceFactory<Produces extends IService<symbol>[], Consumes extends IService<symbol>[]> = (...dependencies: [...Consumes]) => Produces extends [] ? Partial<BABYLON.IDisposable> | void : Partial<BABYLON.IDisposable> & UnionToIntersection<Produces[number]>;
     /**
      * Defines a service, which is a logical unit that consumes other services (dependencies), and optionally produces services that can be consumed by other services (dependents).
      */
@@ -3289,20 +3720,19 @@ declare namespace BABYLON.NodeParticleEditor.SharedUIComponents {
          */
         constructor(_friendlyName: string, _parent?: ServiceContainer | undefined);
         /**
-         * Adds a set of service definitions in the service container.
+         * Adds a set of service definitions to the service container.
          * The services are sorted based on their dependencies.
-         * @param args The service definitions to register, and optionally an abort signal.
-         * @returns A disposable that will remove the service definition from the service container.
+         * @param serviceDefinitions The service definitions to register.
+         * @returns A disposable that will remove the service definitions from the service container.
          */
-        addServicesAsync(...args: WeaklyTypedServiceDefinition[] | [...serviceDefinitions: WeaklyTypedServiceDefinition[], abortSignal: AbortSignal]): Promise<BABYLON.IDisposable>;
+        addServices(...serviceDefinitions: WeaklyTypedServiceDefinition[]): BABYLON.IDisposable;
         /**
          * Registers a service definition in the service container.
          * @param serviceDefinition The service definition to register.
-         * @param abortSignal An optional abort signal.
          * @returns A disposable that will remove the service definition from the service container.
          */
-        addServiceAsync<Produces extends BABYLON.NodeParticleEditor.SharedUIComponents.IService<symbol>[] = [], Consumes extends BABYLON.NodeParticleEditor.SharedUIComponents.IService<symbol>[] = []>(serviceDefinition: BABYLON.NodeParticleEditor.SharedUIComponents.ServiceDefinition<Produces, Consumes>, abortSignal?: AbortSignal): Promise<BABYLON.IDisposable>;
-        private _addServiceAsync;
+        addService<Produces extends BABYLON.NodeParticleEditor.SharedUIComponents.IService<symbol>[] = [], Consumes extends BABYLON.NodeParticleEditor.SharedUIComponents.IService<symbol>[] = []>(serviceDefinition: BABYLON.NodeParticleEditor.SharedUIComponents.ServiceDefinition<Produces, Consumes>): BABYLON.IDisposable;
+        private _addService;
         /**
          * Resolves a dependency by contract identity for a consuming service.
          * Checks local services first, then walks up the parent chain.