@syllm/brickly-sdk 0.1.0

package/dist/api.js

@@ -0,0 +1,995 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BricklyRuntime = exports.WindowHandle = exports.BrickSession = void 0;
+const node_events_1 = require("node:events");
+const node_async_hooks_1 = require("node:async_hooks");
+const errors_1 = require("./errors");
+const runtime_1 = require("./runtime");
+const protocol_1 = require("./protocol");
+const commandScope = new node_async_hooks_1.AsyncLocalStorage();
+function currentCommandScope() {
+    return commandScope.getStore();
+}
+class BrickSession {
+    transport;
+    id;
+    brickId;
+    profileId;
+    constructor(transport, id, brickId, profileId) {
+        this.transport = transport;
+        this.id = id;
+        this.brickId = brickId;
+        this.profileId = profileId;
+    }
+    invoke(commandId, input = null) {
+        const parentRequestId = currentCommandScope()?.requestId;
+        if (!parentRequestId) {
+            return Promise.reject(new errors_1.BppError('PARENT_INVOCATION_REQUIRED', 'session.invoke() must run inside command handler'));
+        }
+        return this.transport.hostCall({
+            type: 'host.session.invoke',
+            sessionId: this.id,
+            commandId,
+            input,
+            parentRequestId
+        });
+    }
+    async close() {
+        await this.transport.hostCall({
+            type: 'host.session.close',
+            sessionId: this.id
+        });
+    }
+}
+exports.BrickSession = BrickSession;
+function pointPayload(xOrPayload, y) {
+    return typeof xOrPayload === 'number' ? { x: xOrPayload, y: y } : xOrPayload;
+}
+/** 子窗口句柄。close() 调 host.ui.closeWindow，其余方法走 host.ui.callWindow。 */
+class WindowHandle extends node_events_1.EventEmitter {
+    id;
+    transport;
+    closed = false;
+    constructor(transport, windowId) {
+        super();
+        this.transport = transport;
+        this.id = windowId;
+    }
+    /** 通用：调用窗口白名单方法。 */
+    call(method, args = []) {
+        if (method === 'webContents.send') {
+            const [channel, ...sendArgs] = args;
+            if (typeof channel !== 'string') {
+                return Promise.reject(new errors_1.BppError('INVALID_INPUT', 'webContents.send requires channel'));
+            }
+            return this.sendToWebContents(channel, sendArgs);
+        }
+        if (this.closed && method !== 'isDestroyed') {
+            return Promise.reject(new errors_1.BppError('INVALID_INPUT', `Window ${this.id} already closed`));
+        }
+        return this.transport.hostCall({
+            type: 'host.ui.callWindow',
+            windowId: this.id,
+            method,
+            args
+        });
+    }
+    sendToWebContents(channel, args) {
+        if (this.closed) {
+            return Promise.reject(new errors_1.BppError('INVALID_INPUT', `Window ${this.id} already closed`));
+        }
+        const parentRequestId = currentCommandScope()?.requestId ?? explicitPayloadRequestId(args);
+        if (!parentRequestId) {
+            return Promise.reject(new errors_1.BppError('PARENT_INVOCATION_REQUIRED', 'webContents.send() must run inside command handler or include payload.requestId'));
+        }
+        return this.transport.hostCall({
+            type: 'host.ui.callWindow',
+            windowId: this.id,
+            method: 'webContents.send',
+            args: [channel, ...args],
+            parentRequestId
+        });
+    }
+    /** 订阅该窗口的网络检查事件。需在 createBrowserWindow options.network 中开启。 */
+    onNetwork(handler) {
+        this.on('network', handler);
+        return this;
+    }
+    // —— 便捷包装：完整覆盖 BrickWindowMethod 白名单（41 个） ——
+    // 几何 / 位置
+    setBounds(bounds) {
+        return this.call('setBounds', [bounds]);
+    }
+    getBounds() {
+        return this.call('getBounds');
+    }
+    setPosition(x, y) {
+        return this.call('setPosition', [x, y]);
+    }
+    getPosition() {
+        return this.call('getPosition');
+    }
+    setSize(width, height) {
+        return this.call('setSize', [width, height]);
+    }
+    getSize() {
+        return this.call('getSize');
+    }
+    // 视觉属性
+    setOpacity(opacity) {
+        return this.call('setOpacity', [opacity]);
+    }
+    getOpacity() {
+        return this.call('getOpacity');
+    }
+    setBackgroundColor(color) {
+        return this.call('setBackgroundColor', [color]);
+    }
+    setHasShadow(hasShadow) {
+        return this.call('setHasShadow', [hasShadow]);
+    }
+    setTitle(title) {
+        return this.call('setTitle', [title]);
+    }
+    getTitle() {
+        return this.call('getTitle');
+    }
+    // 层叠 / 鼠标
+    setAlwaysOnTop(flag, level) {
+        return this.call('setAlwaysOnTop', level === undefined ? [flag] : [flag, level]);
+    }
+    isAlwaysOnTop() {
+        return this.call('isAlwaysOnTop');
+    }
+    setIgnoreMouseEvents(ignore, opts) {
+        return this.call('setIgnoreMouseEvents', opts === undefined ? [ignore] : [ignore, opts]);
+    }
+    setSkipTaskbar(skip) {
+        return this.call('setSkipTaskbar', [skip]);
+    }
+    setVisibleOnAllWorkspaces(visible, opts) {
+        return this.call('setVisibleOnAllWorkspaces', opts === undefined ? [visible] : [visible, opts]);
+    }
+    // 可交互性开关
+    setResizable(resizable) {
+        return this.call('setResizable', [resizable]);
+    }
+    setMovable(movable) {
+        return this.call('setMovable', [movable]);
+    }
+    setFocusable(focusable) {
+        return this.call('setFocusable', [focusable]);
+    }
+    // 状态切换
+    minimize() {
+        return this.call('minimize');
+    }
+    maximize() {
+        return this.call('maximize');
+    }
+    unmaximize() {
+        return this.call('unmaximize');
+    }
+    restore() {
+        return this.call('restore');
+    }
+    hide() {
+        return this.call('hide');
+    }
+    show() {
+        return this.call('show');
+    }
+    showInactive() {
+        return this.call('showInactive');
+    }
+    focus() {
+        return this.call('focus');
+    }
+    blur() {
+        return this.call('blur');
+    }
+    // 状态查询
+    isDestroyed() {
+        return this.call('isDestroyed');
+    }
+    isVisible() {
+        return this.call('isVisible');
+    }
+    isFocused() {
+        return this.call('isFocused');
+    }
+    isMinimized() {
+        return this.call('isMinimized');
+    }
+    isMaximized() {
+        return this.call('isMaximized');
+    }
+    // 内容加载
+    loadURL(url, options) {
+        return this.call('loadURL', options === undefined ? [url] : [url, options]);
+    }
+    loadFile(filePath, options) {
+        return this.call('loadFile', options === undefined ? [filePath] : [filePath, options]);
+    }
+    reload() {
+        return this.call('reload');
+    }
+    // —— v0.2 扩展窗口方法 ——
+    // 内容区域几何（区分窗口外框 vs 网页内容）
+    setContentBounds(bounds) {
+        return this.call('setContentBounds', [bounds]);
+    }
+    getContentBounds() {
+        return this.call('getContentBounds');
+    }
+    setContentSize(width, height) {
+        return this.call('setContentSize', [width, height]);
+    }
+    getContentSize() {
+        return this.call('getContentSize');
+    }
+    setMinimumSize(width, height) {
+        return this.call('setMinimumSize', [width, height]);
+    }
+    getMinimumSize() {
+        return this.call('getMinimumSize');
+    }
+    setMaximumSize(width, height) {
+        return this.call('setMaximumSize', [width, height]);
+    }
+    getMaximumSize() {
+        return this.call('getMaximumSize');
+    }
+    setAspectRatio(aspectRatio, extraSize) {
+        return this.call('setAspectRatio', extraSize === undefined ? [aspectRatio] : [aspectRatio, extraSize]);
+    }
+    /** 获取窗口在非最大化/全屏/最小化时的"普通"位置和尺寸。 */
+    getNormalBounds() {
+        return this.call('getNormalBounds');
+    }
+    // 居中 / 层叠
+    center() {
+        return this.call('center');
+    }
+    moveTop() {
+        return this.call('moveTop');
+    }
+    /** mediaSourceId 由 Electron getMediaSourceId 提供；通常在同 Brick 多窗口间使用。 */
+    moveAbove(mediaSourceId) {
+        return this.call('moveAbove', [mediaSourceId]);
+    }
+    // 全屏 / 状态查询
+    setFullScreen(flag) {
+        return this.call('setFullScreen', [flag]);
+    }
+    isFullScreen() {
+        return this.call('isFullScreen');
+    }
+    isNormal() {
+        return this.call('isNormal');
+    }
+    isModal() {
+        return this.call('isModal');
+    }
+    /** 强制销毁窗口（不触发 close 事件），等价于 BrowserWindow.destroy()。慎用。 */
+    destroy() {
+        this.closed = true;
+        return this.call('destroy');
+    }
+    // 能力查询（与 setter 配对）
+    isResizable() {
+        return this.call('isResizable');
+    }
+    isMovable() {
+        return this.call('isMovable');
+    }
+    isFocusable() {
+        return this.call('isFocusable');
+    }
+    setMinimizable(flag) {
+        return this.call('setMinimizable', [flag]);
+    }
+    isMinimizable() {
+        return this.call('isMinimizable');
+    }
+    setMaximizable(flag) {
+        return this.call('setMaximizable', [flag]);
+    }
+    isMaximizable() {
+        return this.call('isMaximizable');
+    }
+    setClosable(flag) {
+        return this.call('setClosable', [flag]);
+    }
+    isClosable() {
+        return this.call('isClosable');
+    }
+    setFullScreenable(flag) {
+        return this.call('setFullScreenable', [flag]);
+    }
+    isFullScreenable() {
+        return this.call('isFullScreenable');
+    }
+    setEnabled(enabled) {
+        return this.call('setEnabled', [enabled]);
+    }
+    isEnabled() {
+        return this.call('isEnabled');
+    }
+    hasShadow() {
+        return this.call('hasShadow');
+    }
+    isVisibleOnAllWorkspaces() {
+        return this.call('isVisibleOnAllWorkspaces');
+    }
+    setKiosk(flag) {
+        return this.call('setKiosk', [flag]);
+    }
+    isKiosk() {
+        return this.call('isKiosk');
+    }
+    // 视觉提醒 / 任务栏 / 菜单栏
+    flashFrame(flag) {
+        return this.call('flashFrame', [flag]);
+    }
+    /**
+     * 任务栏进度条。progress：[0,1] 显示进度；-1 关闭；>1 不确定。
+     * options.mode: 'none' | 'normal' | 'indeterminate' | 'error' | 'paused'。
+     */
+    setProgressBar(progress, options) {
+        return this.call('setProgressBar', options === undefined ? [progress] : [progress, options]);
+    }
+    setMenuBarVisibility(visible) {
+        return this.call('setMenuBarVisibility', [visible]);
+    }
+    isMenuBarVisible() {
+        return this.call('isMenuBarVisible');
+    }
+    setAutoHideMenuBar(hide) {
+        return this.call('setAutoHideMenuBar', [hide]);
+    }
+    isMenuBarAutoHide() {
+        return this.call('isMenuBarAutoHide');
+    }
+    removeMenu() {
+        return this.call('removeMenu');
+    }
+    /** macOS 透明窗口在内容大小变化后需手动失效阴影。 */
+    invalidateShadow() {
+        return this.call('invalidateShadow');
+    }
+    // macOS 文档窗口标识
+    setRepresentedFilename(path) {
+        return this.call('setRepresentedFilename', [path]);
+    }
+    getRepresentedFilename() {
+        return this.call('getRepresentedFilename');
+    }
+    setDocumentEdited(edited) {
+        return this.call('setDocumentEdited', [edited]);
+    }
+    isDocumentEdited() {
+        return this.call('isDocumentEdited');
+    }
+    /**
+     * 类 Electron 风格的 webContents 子对象。等价于直接调用 `webContentsSend` 等方法，
+     * 但写法更接近 uTools / Electron 原生：`win.webContents.send('ch', payload)`。
+     */
+    webContents = {
+        send: (channel, ...args) => this.sendToWebContents(channel, args),
+        executeJavaScript: (code, userGesture) => this.call('webContents.executeJavaScript', userGesture === undefined ? [code] : [code, userGesture]),
+        openDevTools: (options) => this.call('webContents.openDevTools', options === undefined ? [] : [options]),
+        closeDevTools: () => this.call('webContents.closeDevTools'),
+        toggleDevTools: () => this.call('webContents.toggleDevTools'),
+        isDevToolsOpened: () => this.call('webContents.isDevToolsOpened'),
+        // 导航
+        goBack: () => this.call('webContents.goBack'),
+        goForward: () => this.call('webContents.goForward'),
+        canGoBack: () => this.call('webContents.canGoBack'),
+        canGoForward: () => this.call('webContents.canGoForward'),
+        getURL: () => this.call('webContents.getURL'),
+        getTitle: () => this.call('webContents.getTitle'),
+        // 缩放
+        setZoomFactor: (factor) => this.call('webContents.setZoomFactor', [factor]),
+        getZoomFactor: () => this.call('webContents.getZoomFactor'),
+        setZoomLevel: (level) => this.call('webContents.setZoomLevel', [level]),
+        getZoomLevel: () => this.call('webContents.getZoomLevel'),
+        // 编辑命令
+        copy: () => this.call('webContents.copy'),
+        paste: () => this.call('webContents.paste'),
+        cut: () => this.call('webContents.cut'),
+        selectAll: () => this.call('webContents.selectAll'),
+        undo: () => this.call('webContents.undo'),
+        redo: () => this.call('webContents.redo')
+    };
+    /** webContents.send 旧别名，保留向后兼容。新代码请用 `win.webContents.send(...)`。 */
+    webContentsSend(channel, ...args) {
+        return this.webContents.send(channel, ...args);
+    }
+    /** 关闭窗口（不可逆）。走 host.ui.closeWindow，而非白名单 close 方法。 */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.transport.hostCall({
+            type: 'host.ui.closeWindow',
+            windowId: this.id
+        });
+    }
+    /** 内部：由 BricklyRuntime 在收到对应 window.* 事件时调用。 */
+    _emit(eventName, payload) {
+        if (eventName === 'closed')
+            this.closed = true;
+        this.emit(eventName, payload);
+    }
+}
+exports.WindowHandle = WindowHandle;
+function explicitPayloadRequestId(args) {
+    const payload = args[0];
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const requestId = payload.requestId;
+    return typeof requestId === 'string' && requestId ? requestId : undefined;
+}
+/**
+ * Brick SDK 主入口。典型用法：
+ *
+ *   const brick = new BricklyRuntime({ brickId: 'com.example.foo' })
+ *   brick.onCommand('do-it', async (ctx, input) => { ... })
+ *   brick.onReady(async () => { ... })
+ *   brick.start()
+ */
+class BricklyRuntime {
+    brickId;
+    transport;
+    protocolVersion;
+    commandHandlers = new Map();
+    cancelHandlers = new Map();
+    cancelled = new Set();
+    eventListeners = new Map();
+    windows = new Map();
+    readyHandler;
+    shutdownHandler;
+    config = {};
+    started = false;
+    exiting = false;
+    hostPidWatchdog;
+    constructor(opts) {
+        this.brickId = opts.brickId;
+        this.protocolVersion = opts.protocolVersion ?? protocol_1.PROTOCOL_VERSION;
+        this.transport = new runtime_1.BppTransport(opts);
+        this.transport.on('error', (err) => this.transport.log('transport error:', String(err)));
+        this.transport.on('message', (msg) => this.handleHello(msg));
+        this.transport.on('command', (msg) => this.handleCommand(msg));
+        this.transport.on('event', (msg) => this.handleEvent(msg));
+        this.transport.on('shutdown', () => void this.handleShutdown());
+        this.transport.on('host-disconnect', () => void this.handleHostDisconnect());
+    }
+    /** 注册 command 处理器。 */
+    onCommand(commandId, handler) {
+        this.commandHandlers.set(commandId, handler);
+        return this;
+    }
+    /** 注册 runtime.ready 之后立即执行的钩子（适合 host-start service 或实例初始化逻辑）。 */
+    onReady(handler) {
+        this.readyHandler = handler;
+        return this;
+    }
+    /** 注册 runtime.shutdown 处理逻辑；返回后 SDK 自动发送 runtime.bye 并退出。 */
+    onShutdown(handler) {
+        this.shutdownHandler = handler;
+        return this;
+    }
+    /** 子窗口 / UI API。 */
+    ui = {
+        createBrowserWindow: async (url, options) => {
+            const result = await this.transport.hostCall({
+                type: 'host.ui.createBrowserWindow',
+                url,
+                options
+            });
+            const handle = new WindowHandle(this.transport, result.windowId);
+            this.windows.set(result.windowId, handle);
+            handle.once('closed', () => this.windows.delete(result.windowId));
+            return handle;
+        },
+        listWindows: () => this.transport.hostCall({
+            type: 'host.ui.listWindows'
+        })
+    };
+    /** 事件订阅 API。 */
+    events = {
+        on: (event, handler) => {
+            let set = this.eventListeners.get(event);
+            if (!set) {
+                set = new Set();
+                this.eventListeners.set(event, set);
+            }
+            set.add(handler);
+            return () => {
+                set.delete(handler);
+                if (set.size === 0)
+                    this.eventListeners.delete(event);
+            };
+        },
+        publish: (event, payload) => this.transport.hostCall({
+            type: 'host.event.publish',
+            event,
+            payload
+        })
+    };
+    /** 宿主平台能力 API。 */
+    platform = {
+        screenshot: {
+            selectRegion: (options) => this.transport.hostCall({
+                type: 'host.platform.screenshot.selectRegion',
+                options
+            })
+        },
+        screen: {
+            captureRegion: (options) => this.transport.hostCall({
+                type: 'host.platform.screen.captureRegion',
+                options
+            }),
+            pickColor: (options) => this.transport.hostCall({
+                type: 'host.platform.screen.pickColor',
+                options
+            }),
+            getPrimaryDisplay: () => this.transport.hostCall({
+                type: 'host.platform.screen.getPrimaryDisplay'
+            }),
+            getAllDisplays: () => this.transport.hostCall({
+                type: 'host.platform.screen.getAllDisplays'
+            }),
+            getCursorScreenPoint: () => this.transport.hostCall({
+                type: 'host.platform.screen.getCursorScreenPoint'
+            }),
+            getDisplayNearestPoint: (point) => this.transport.hostCall({
+                type: 'host.platform.screen.getDisplayNearestPoint',
+                point
+            }),
+            getDisplayMatching: (rect) => this.transport.hostCall({
+                type: 'host.platform.screen.getDisplayMatching',
+                rect
+            }),
+            screenToDipPoint: (point) => this.transport.hostCall({
+                type: 'host.platform.screen.screenToDipPoint',
+                point
+            }),
+            dipToScreenPoint: (point) => this.transport.hostCall({
+                type: 'host.platform.screen.dipToScreenPoint',
+                point
+            }),
+            screenToDipRect: (rect) => this.transport.hostCall({
+                type: 'host.platform.screen.screenToDipRect',
+                rect
+            }),
+            dipToScreenRect: (rect) => this.transport.hostCall({
+                type: 'host.platform.screen.dipToScreenRect',
+                rect
+            }),
+            desktopCaptureSources: (options) => this.transport.hostCall({
+                type: 'host.platform.screen.desktopCaptureSources',
+                options
+            })
+        },
+        input: {
+            keyboardTap: (keyOrPayload, ...modifiers) => this.transport.hostCall({
+                type: 'host.platform.input.keyboardTap',
+                payload: typeof keyOrPayload === 'string' ? { key: keyOrPayload, modifiers } : keyOrPayload
+            }),
+            mouseMove: (xOrPayload, y) => this.transport.hostCall({
+                type: 'host.platform.input.mouseMove',
+                payload: pointPayload(xOrPayload, y)
+            }),
+            mouseClick: (xOrPayload, y) => this.transport.hostCall({
+                type: 'host.platform.input.mouseClick',
+                payload: pointPayload(xOrPayload, y)
+            }),
+            mouseDoubleClick: (xOrPayload, y) => this.transport.hostCall({
+                type: 'host.platform.input.mouseDoubleClick',
+                payload: pointPayload(xOrPayload, y)
+            }),
+            mouseRightClick: (xOrPayload, y) => this.transport.hostCall({
+                type: 'host.platform.input.mouseRightClick',
+                payload: pointPayload(xOrPayload, y)
+            })
+        },
+        clipboard: {
+            readContent: () => this.transport.hostCall({
+                type: 'host.platform.clipboard.readContent'
+            }),
+            setContent: (content) => this.transport.hostCall({
+                type: 'host.platform.clipboard.setContent',
+                content
+            })
+        },
+        system: {
+            showNotification: (body, clickFeatureCode) => this.transport.hostCall({
+                type: 'host.platform.system.showNotification',
+                body,
+                ...(clickFeatureCode ? { clickFeatureCode } : {})
+            }),
+            shellOpenPath: (fullPath) => this.transport.hostCall({
+                type: 'host.platform.system.shellOpenPath',
+                fullPath
+            }),
+            shellTrashItem: (fullPath) => this.transport.hostCall({
+                type: 'host.platform.system.shellTrashItem',
+                fullPath
+            }),
+            shellShowItemInFolder: (fullPath) => this.transport.hostCall({
+                type: 'host.platform.system.shellShowItemInFolder',
+                fullPath
+            }),
+            shellOpenExternal: (url) => this.transport.hostCall({
+                type: 'host.platform.system.shellOpenExternal',
+                url
+            }),
+            shellBeep: () => this.transport.hostCall({
+                type: 'host.platform.system.shellBeep'
+            }),
+            getNativeId: () => this.transport.hostCall({
+                type: 'host.platform.system.getNativeId'
+            }),
+            getAppName: () => this.transport.hostCall({
+                type: 'host.platform.system.getAppName'
+            }),
+            getAppVersion: () => this.transport.hostCall({
+                type: 'host.platform.system.getAppVersion'
+            }),
+            getPath: (name) => this.transport.hostCall({
+                type: 'host.platform.system.getPath',
+                name
+            }),
+            getFileIcon: (filePath) => this.transport.hostCall({
+                type: 'host.platform.system.getFileIcon',
+                filePath
+            }),
+            readCurrentFolderPath: () => this.transport.hostCall({
+                type: 'host.platform.system.readCurrentFolderPath'
+            }),
+            readCurrentBrowserUrl: () => this.transport.hostCall({
+                type: 'host.platform.system.readCurrentBrowserUrl'
+            }),
+            isDev: () => this.transport.hostCall({
+                type: 'host.platform.system.isDev'
+            }),
+            isMacOS: () => this.transport.hostCall({
+                type: 'host.platform.system.isMacOS'
+            }),
+            isWindows: () => this.transport.hostCall({
+                type: 'host.platform.system.isWindows'
+            }),
+            isLinux: () => this.transport.hostCall({
+                type: 'host.platform.system.isLinux'
+            })
+        }
+    };
+    /** 启动 stdin 循环。 */
+    start() {
+        if (this.started)
+            return this;
+        this.started = true;
+        this.transport.start();
+        this.startHostPidWatchdog();
+        return this;
+    }
+    /** 停止 stdin 循环（一般不需要主动调，runtime.shutdown 会自动处理）。 */
+    stop() {
+        if (this.hostPidWatchdog) {
+            clearInterval(this.hostPidWatchdog);
+            this.hostPidWatchdog = undefined;
+        }
+        this.transport.stop('brick stopped');
+    }
+    invoke(brickId, commandId, input = null, options) {
+        const parentRequestId = currentCommandScope()?.requestId;
+        if (!parentRequestId) {
+            return Promise.reject(new errors_1.BppError('PARENT_INVOCATION_REQUIRED', 'invoke() must run inside command handler; use invokeRoot() for root calls'));
+        }
+        return this.transport.hostCall({
+            type: 'host.invoke',
+            brickId,
+            commandId,
+            input,
+            parentRequestId,
+            ...(options?.profileId ? { profileId: options.profileId } : {})
+        });
+    }
+    invokeRoot(brickId, commandId, input = null, options) {
+        return this.transport.hostCall({
+            type: 'host.invokeRoot',
+            brickId,
+            commandId,
+            input,
+            ...(options?.profileId ? { profileId: options.profileId } : {})
+        });
+    }
+    invokeStream(brickId, commandId, input = null, options) {
+        return this.hostInvokeStream(brickId, commandId, input, options);
+    }
+    hostInvokeStream(brickId, commandId, input, options) {
+        const parentRequestId = currentCommandScope()?.requestId;
+        if (!parentRequestId) {
+            throw new errors_1.BppError('PARENT_INVOCATION_REQUIRED', 'invokeStream() must run inside command handler');
+        }
+        const transport = this.transport;
+        const id = transport.nextHostId();
+        const queue = [];
+        const waiters = [];
+        let done = false;
+        let cleanedUp = false;
+        const push = (event, finish = false) => {
+            queue.push(event);
+            done ||= finish;
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter({ value: queue.shift(), done: false });
+        };
+        const pushError = (error) => {
+            push({ type: 'error', error: errors_1.BppError.from(error) }, true);
+            cleanup();
+        };
+        const onMessage = (msg) => {
+            if (!('id' in msg) || msg.id !== id)
+                return;
+            if (msg.type === 'host.invoke.progress') {
+                push({ type: 'progress', progress: msg.progress, message: msg.message });
+            }
+            else if (msg.type === 'host.invoke.chunk') {
+                push({ type: 'chunk', name: msg.name, chunk: msg.chunk });
+            }
+            else if (msg.type === 'host.invoke.output') {
+                push({ type: 'output', name: msg.name, value: msg.value });
+            }
+            else if (msg.type === 'host.result') {
+                push({ type: 'result', result: msg.result }, true);
+                cleanup();
+            }
+            else if (msg.type === 'host.error') {
+                push({ type: 'error', error: (0, errors_1.payloadToError)(msg.error) }, true);
+                cleanup();
+            }
+        };
+        const onEnd = () => {
+            pushError(new errors_1.BppError('PROCESS_EXITED', 'host pipe closed'));
+        };
+        const onError = (err) => {
+            pushError(new errors_1.BppError('PROCESS_EXITED', 'host pipe error', { error: err }));
+        };
+        const cleanup = () => {
+            if (cleanedUp)
+                return;
+            cleanedUp = true;
+            transport.off('message', onMessage);
+            transport.off('end', onEnd);
+            transport.off('error', onError);
+        };
+        transport.on('message', onMessage);
+        transport.once('end', onEnd);
+        transport.once('error', onError);
+        transport.send({
+            type: 'host.invoke',
+            id,
+            brickId,
+            commandId,
+            input,
+            parentRequestId,
+            stream: true,
+            ...(options?.profileId ? { profileId: options.profileId } : {})
+        });
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next: () => {
+                        const event = queue.shift();
+                        if (event)
+                            return Promise.resolve({ value: event, done: false });
+                        if (done)
+                            return Promise.resolve({ value: undefined, done: true });
+                        return new Promise((resolve) => waiters.push(resolve));
+                    },
+                    return: () => {
+                        done = true;
+                        cleanup();
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                };
+            }
+        };
+    }
+    async openSession(brickId, options) {
+        const result = await this.transport.hostCall({
+            type: 'host.session.open',
+            brickId,
+            ...(options?.profileId ? { profileId: options.profileId } : {})
+        });
+        return new BrickSession(this.transport, result.sessionId, result.brickId, result.profileId);
+    }
+    // —— 内部分发 ——
+    handleHello(msg) {
+        if (msg.type !== 'host.hello')
+            return;
+        this.config = msg.config && typeof msg.config === 'object' ? msg.config : {};
+        this.transport.send({
+            type: 'runtime.ready',
+            protocolVersion: this.protocolVersion,
+            brickId: this.brickId
+        });
+        if (this.readyHandler) {
+            Promise.resolve()
+                .then(() => this.readyHandler?.())
+                .catch((err) => this.transport.log('onReady error:', errors_1.BppError.from(err).message));
+        }
+    }
+    handleCommand(msg) {
+        if (msg.type === 'command.cancel') {
+            this.cancelled.add(msg.id);
+            const fn = this.cancelHandlers.get(msg.id);
+            if (fn) {
+                try {
+                    fn();
+                }
+                catch (err) {
+                    this.transport.log('cancel handler error:', errors_1.BppError.from(err).message);
+                }
+            }
+            return;
+        }
+        if (msg.type !== 'command.invoke')
+            return;
+        const handler = this.commandHandlers.get(msg.commandId);
+        const reqId = msg.id;
+        if (!handler) {
+            this.transport.send({
+                type: 'command.error',
+                id: reqId,
+                error: {
+                    code: 'COMMAND_NOT_FOUND',
+                    message: `Unknown command: ${msg.commandId}`
+                }
+            });
+            return;
+        }
+        const ctx = this.buildContext(reqId, msg.commandId, msg.invocation);
+        Promise.resolve()
+            .then(() => commandScope.run({ requestId: reqId }, () => handler(ctx, msg.input)))
+            .then((result) => {
+            this.transport.send({ type: 'command.result', id: reqId, result });
+        })
+            .catch((err) => {
+            const e = errors_1.BppError.from(err);
+            this.transport.send({ type: 'command.error', id: reqId, error: e.toJSON() });
+        })
+            .finally(() => {
+            this.cancelled.delete(reqId);
+            this.cancelHandlers.delete(reqId);
+        });
+    }
+    handleEvent(msg) {
+        if (msg.type !== 'event.notify')
+            return;
+        const env = {
+            event: msg.event,
+            payload: msg.payload,
+            sourceBrickId: msg.sourceBrickId,
+            publishedAt: msg.publishedAt
+        };
+        // 转发到 WindowHandle：window.* 事件如果 payload.windowId 命中已知窗口，路由到句柄。
+        if (msg.event.startsWith('window.')) {
+            const wid = msg.payload?.windowId;
+            if (typeof wid === 'number') {
+                const handle = this.windows.get(wid);
+                if (handle) {
+                    const subEvent = msg.event.slice('window.'.length);
+                    handle._emit(subEvent, msg.payload);
+                }
+            }
+        }
+        const set = this.eventListeners.get(msg.event);
+        if (set) {
+            for (const fn of set) {
+                try {
+                    fn(msg.payload, env);
+                }
+                catch (err) {
+                    this.transport.log('event handler error:', errors_1.BppError.from(err).message);
+                }
+            }
+        }
+    }
+    async handleShutdown() {
+        if (this.exiting)
+            return;
+        this.exiting = true;
+        try {
+            if (this.shutdownHandler)
+                await this.shutdownHandler();
+        }
+        catch (err) {
+            this.transport.log('shutdown handler error:', errors_1.BppError.from(err).message);
+        }
+        this.transport.send({ type: 'runtime.bye' });
+        // 留一点时间把字节冲出去再退出
+        setTimeout(() => process.exit(0), 50).unref?.();
+    }
+    async handleHostDisconnect() {
+        if (this.exiting)
+            return;
+        this.exiting = true;
+        this.transport.log('host disconnected; exiting brick runtime');
+        try {
+            if (this.shutdownHandler)
+                await this.shutdownHandler();
+        }
+        catch (err) {
+            this.transport.log('host disconnect cleanup error:', errors_1.BppError.from(err).message);
+        }
+        setTimeout(() => process.exit(0), 50).unref?.();
+    }
+    startHostPidWatchdog() {
+        const rawPid = process.env.BRICKLY_HOST_PID;
+        if (!rawPid)
+            return;
+        const hostPid = Number(rawPid);
+        if (!Number.isInteger(hostPid) || hostPid <= 0)
+            return;
+        this.hostPidWatchdog = setInterval(() => {
+            try {
+                process.kill(hostPid, 0);
+            }
+            catch {
+                if (this.hostPidWatchdog) {
+                    clearInterval(this.hostPidWatchdog);
+                    this.hostPidWatchdog = undefined;
+                }
+                void this.handleHostDisconnect();
+            }
+        }, 5000);
+        this.hostPidWatchdog.unref?.();
+    }
+    buildContext(reqId, commandId, invocation) {
+        const resolvedInvocation = invocation ?? { source: 'unknown' };
+        const withInvocationProfile = (brickId, options) => {
+            if (options?.profileId)
+                return options;
+            const profileId = resolvedInvocation.dependencyProfiles?.[brickId];
+            if (!profileId)
+                return options;
+            return { ...(options ?? {}), profileId };
+        };
+        const invoke = ((brickId, targetCommandId, input, options) => this.invoke(brickId, targetCommandId, input, withInvocationProfile(brickId, options)));
+        const openSession = ((brickId, options) => this.openSession(brickId, withInvocationProfile(brickId, options)));
+        const invokeStream = ((brickId, targetCommandId, input, options) => this.hostInvokeStream(brickId, targetCommandId, input, withInvocationProfile(brickId, options)));
+        return {
+            requestId: reqId,
+            commandId,
+            invocation: resolvedInvocation,
+            onCancel: (fn) => {
+                this.cancelHandlers.set(reqId, fn);
+                // 如果取消信号已经到了，立刻触发
+                if (this.cancelled.has(reqId)) {
+                    try {
+                        fn();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            },
+            isCancelled: () => this.cancelled.has(reqId),
+            progress: (value, message) => this.transport.send({ type: 'command.progress', id: reqId, progress: value, message }),
+            chunk: (chunk, name) => this.transport.send({ type: 'command.chunk', id: reqId, name, chunk }),
+            output: (name, value) => this.transport.send({ type: 'command.output', id: reqId, name, value }),
+            invoke,
+            invokeStream,
+            openSession,
+            ui: this.ui,
+            events: this.events,
+            platform: this.platform,
+            config: this.config
+        };
+    }
+}
+exports.BricklyRuntime = BricklyRuntime;