@pipedog/core 0.0.0 → 0.2.0

package/dist/workers/runner.js

@@ -0,0 +1,489 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/runner.py
+/**
+ * Worker runner for managing worker execution and orchestration.
+ *
+ * This module provides the `WorkerRunner` class. It runs `BaseWorker`
+ * instances (including `PipelineWorker`) to completion, owning the shared
+ * `WorkerBus`, the worker registry, and the worker manager that backs the
+ * entire session.
+ *
+ * For a typical single-pipeline bot, register the worker with
+ * `WorkerRunner.addWorkers` and then call `WorkerRunner.run`:
+ *
+ * @example
+ * ```ts
+ * const runner = new WorkerRunner();
+ * await runner.addWorkers(worker);
+ * await runner.run();
+ * ```
+ *
+ * For multi-worker setups, register every worker the same way:
+ *
+ * @example
+ * ```ts
+ * const runner = new WorkerRunner();
+ * await runner.addWorkers(new CodeWorker("code-worker", ...), worker);
+ * await runner.run();
+ * ```
+ *
+ * By default, `run()` ends once every root worker has finished — so a
+ * single-pipeline bot naturally ends when its pipeline does. Multi-worker
+ * bots whose helpers run forever (e.g. waiting for bus messages) end by
+ * calling `WorkerRunner.end` / `WorkerRunner.cancel` from an event handler
+ * (typically on transport disconnect). For long-lived hosts that add and
+ * remove workers over many sessions (e.g. an HTTP server), pass
+ * `autoEnd: false` to `run()` so the runner does not exit when no workers
+ * are left.
+ */
+import { CancelledError, createTask, Event, gather, gatherSettled, sleep, } from "@pipedog/asyncio";
+import { AsyncQueueBus, BusAddWorkerMessage, BusCancelMessage, BusCancelWorkerMessage, BusEndMessage, BusEndWorkerMessage, BusWorkerRegistryMessage, } from "../bus/index.js";
+import { BusSubscriber } from "../bus/subscriber.js";
+import { PipelineWorker } from "../pipeline/worker.js";
+import { WorkerRegistry } from "../registry/index.js";
+import { WorkerReadyData, WorkerRegistryEntry } from "../registry/types.js";
+import { TaskManager } from "../utils/asyncio/task_manager.js";
+import { BaseObject } from "../utils/base_object.js";
+import { logger } from "../utils/logger.js";
+import { runSetupHook } from "../utils/startup.js";
+import { WorkerParams } from "./base_worker.js";
+/** A worker registered on the runner and its background task. */
+class _WorkerEntry {
+    worker;
+    runnerTask;
+    constructor(options) {
+        this.worker = options.worker;
+        this.runnerTask = options.runnerTask ?? null;
+    }
+}
+/** The host's `process`, when it has one that delivers signals (Bun, Node, Deno). */
+function signalProcess() {
+    const proc = globalThis.process;
+    return proc && typeof proc.on === "function" ? proc : undefined;
+}
+/**
+ * Manages worker execution.
+ *
+ * Provides a high-level interface for running workers with automatic signal
+ * handling (SIGINT/SIGTERM), optional garbage collection, proper cleanup of
+ * resources, and a worker bus + registry for multi-worker orchestration.
+ *
+ * Two entry points:
+ *
+ * - `addWorkers(...workers)` — register one or more workers on the runner's
+ *   bus and start them in the background. Workers run concurrently and
+ *   remaining workers are cancelled when the runner ends.
+ * - `run()` — block until the runner ends. By default (`autoEnd: true`) the
+ *   runner ends once every root worker has finished; pass `autoEnd: false`
+ *   to keep the runner up until `end()` / `cancel()` is called.
+ *
+ * Event handlers available:
+ *
+ * - `on_ready` — fired after the runner has finished its initialization and
+ *   any added workers have been started.
+ * - `on_error` — fired when starting an added worker fails.
+ */
+export class WorkerRunner extends BusSubscriber(BaseObject) {
+    _bus;
+    _registry;
+    _checkDanglingTasks;
+    _entries = new Map();
+    _knownRunners = new Set();
+    _running = false;
+    _autoEnd = true;
+    _cancelReason = null;
+    _shutdownEvent = new Event();
+    _sigTask = null;
+    _handleSigint;
+    _handleSigterm;
+    _forceGc;
+    /**
+     * Initialize the worker runner.
+     *
+     * @param options Runner options (see `WorkerRunnerOptions`).
+     */
+    constructor(options = {}) {
+        const taskManager = options.taskManager || new TaskManager();
+        const name = options.name || `runner-${crypto.randomUUID().replaceAll("-", "").slice(0, 8)}`;
+        super({ name, taskManager });
+        this._bus = options.bus || new AsyncQueueBus();
+        this._registry = new WorkerRegistry(this.name);
+        this._checkDanglingTasks = options.checkDanglingTasks ?? true;
+        this._handleSigint = options.handleSigint ?? true;
+        this._handleSigterm = options.handleSigterm ?? false;
+        this._forceGc = options.forceGc ?? false;
+        this._registerEventHandler("on_ready");
+        this._registerEventHandler("on_error");
+    }
+    /** The bus this runner hosts; shared across launched workers. */
+    get bus() {
+        return this._bus;
+    }
+    /** The worker registry this runner owns. */
+    get registry() {
+        return this._registry;
+    }
+    /**
+     * Look up a worker running on this runner by name.
+     *
+     * Only workers added to this runner have a local instance to return. A
+     * worker on another runner is addressable over the bus by name but has no
+     * object here, so it looks the same as an unknown name.
+     *
+     * @param name The name the worker was created with.
+     * @returns The worker, or null if this runner has no worker by that name.
+     */
+    getWorker(name) {
+        const entry = this._entries.get(name);
+        return entry ? entry.worker : null;
+    }
+    /**
+     * Add one or more workers to the runner.
+     *
+     * Adding a worker attaches it to the runner's bus and registry, and starts
+     * it in the background. If the runner is not yet running (`addWorkers` was
+     * called before `run()`), workers are queued and started during run setup;
+     * if the runner is already running, each worker starts immediately.
+     *
+     * Every added worker is a peer: the runner privileges none of them. They
+     * run concurrently, and whichever are still running when the runner ends
+     * are cancelled. With `autoEnd: true` the runner ends once every root
+     * worker has finished, so a worker that never finishes on its own, such as
+     * a bus-only one waiting for messages, keeps it up until `end()` or
+     * `cancel()` is called.
+     *
+     * @param workers One or more workers to add.
+     */
+    async addWorkers(...workers) {
+        for (const worker of workers) {
+            if (this._entries.has(worker.name)) {
+                logger.error(`WorkerRunner '${this}': worker '${worker.name}' already exists, skipping`);
+                continue;
+            }
+            // `attach` is async because it also subscribes the worker to the bus —
+            // eager subscription is required so workers added later are listening
+            // before earlier workers emit their first messages.
+            await worker.attach({ registry: this._registry, bus: this._bus, workerRunner: this });
+            await this._registry.watch(worker.name, (data) => this._onLocalWorkerReady(data));
+            const entry = new _WorkerEntry({ worker });
+            this._entries.set(worker.name, entry);
+            logger.debug(`WorkerRunner '${this}': added worker '${worker.name}'`);
+            if (this._running) {
+                await this._startWorker(entry);
+            }
+        }
+    }
+    /**
+     * Run all added workers until the runner is stopped.
+     *
+     * By default (`autoEnd: true`), the runner ends once every root worker has
+     * finished — so a single-pipeline bot naturally ends when its pipeline
+     * does. Multi-worker bots whose helpers run forever (e.g. waiting for bus
+     * messages) end by calling `end()` / `cancel()` from an event handler
+     * (typically on transport disconnect). For long-lived hosts that add and
+     * remove workers over many sessions (e.g. an HTTP server), pass
+     * `autoEnd: false` so the runner does not exit when no workers are left.
+     *
+     * @param options.autoEnd When true (the default), the runner ends once
+     *   every root worker has finished. When false, the runner blocks until
+     *   `end()` or `cancel()` is called.
+     */
+    async run(options = {}) {
+        logger.debug(`WorkerRunner '${this}': started running`);
+        this._autoEnd = options.autoEnd ?? true;
+        this._shutdownEvent.clear();
+        await this._setupSession();
+        await this._callEventHandler("on_ready");
+        // Wait for shutdown. With `autoEnd: true`, `_runWorker` sets
+        // `_shutdownEvent` once the last root worker finishes.
+        try {
+            await this._shutdownEvent.wait();
+        }
+        catch (e) {
+            if (!(e instanceof CancelledError))
+                throw e;
+        }
+        try {
+            // Cancel any worker still going and wait for it to finish.
+            await this._cancelSpawnedWorkers();
+            // Cleanup base object.
+            await this.cleanup();
+            // If we are cancelling through a signal, make sure we wait for it so
+            // everything gets cleaned up nicely.
+            if (this._sigTask) {
+                await this._sigTask;
+            }
+        }
+        finally {
+            await this._bus.stop();
+            this._running = false;
+        }
+        if (this._forceGc) {
+            await this._gcCollect();
+        }
+        // Report dangling tasks on the shared task manager after everything has
+        // been torn down. Workers sharing this task manager leave the report to
+        // us; only workers with their own task manager report themselves.
+        this._printDanglingTasks();
+        logger.debug(`WorkerRunner '${this}': finished running`);
+    }
+    /** Schedule all root pipeline workers to stop when their current processing is complete. */
+    async stopWhenDone() {
+        logger.debug(`WorkerRunner '${this}': scheduled to stop when all workers are done`);
+        await gather(...[...this._entries.values()]
+            .filter((entry) => entry.worker instanceof PipelineWorker && entry.worker.parent === null)
+            .map((entry) => () => entry.worker.stopWhenDone()));
+    }
+    /**
+     * Gracefully end all running workers.
+     *
+     * Idempotent; subsequent calls are ignored.
+     *
+     * @param reason Optional human-readable reason for ending.
+     */
+    async end(reason = null) {
+        if (this._shutdownEvent.isSet()) {
+            return;
+        }
+        logger.debug(`WorkerRunner '${this}': ending gracefully (reason=${reason})`);
+        this._shutdownEvent.set();
+        await this._finishRunningWorkers(BusEndWorkerMessage, reason);
+    }
+    /**
+     * Immediately cancel all running workers.
+     *
+     * Signals shutdown, which `run()` answers by cancelling every worker still
+     * going and waiting for it. Idempotent; subsequent calls are ignored.
+     *
+     * @param reason Optional human-readable reason for cancelling. Reaches each
+     *   worker on the cancel message sent as the runner exits.
+     */
+    async cancel(reason = null) {
+        if (this._shutdownEvent.isSet()) {
+            return;
+        }
+        logger.debug(`WorkerRunner '${this}': cancelling (reason=${reason})`);
+        this._cancelReason = reason;
+        this._shutdownEvent.set();
+    }
+    /** Process incoming bus messages for runner-level concerns. */
+    async onBusMessage(message) {
+        if (message.source === this.name) {
+            return;
+        }
+        if (message instanceof BusEndMessage) {
+            this.createTask(() => this.end(message.reason), "end");
+        }
+        else if (message instanceof BusCancelMessage) {
+            this.createTask(() => this.cancel(message.reason), "cancel");
+        }
+        else if (message instanceof BusAddWorkerMessage && message.worker) {
+            await this.addWorkers(message.worker);
+        }
+        else if (message instanceof BusWorkerRegistryMessage) {
+            await this._handleWorkerRegistry(message);
+        }
+    }
+    /** One-time per-run setup: worker manager, bus, signal handlers, launched workers. */
+    async _setupSession() {
+        if (this._running) {
+            return;
+        }
+        await this._bus.setup(this.taskManager);
+        if (this._handleSigint) {
+            this._setupSigint();
+        }
+        if (this._handleSigterm) {
+            this._setupSigterm();
+        }
+        await this._bus.subscribe(this);
+        await this._bus.start();
+        await this._loadSetupFiles();
+        // Running from here on, so a worker that adds another one while it
+        // starts gets it started right away through addWorkers().
+        this._running = true;
+        for (const entry of [...this._entries.values()]) {
+            await this._startWorker(entry);
+        }
+    }
+    /**
+     * Cancel every worker still going and wait for it to finish.
+     *
+     * The one place the runner cancels its workers, reached on every way out:
+     * an ended session, a cancelled one, or the last root worker finishing. A
+     * worker whose task has already finished is left alone.
+     */
+    async _cancelSpawnedWorkers() {
+        const running = await this._finishRunningWorkers(BusCancelWorkerMessage, this._cancelReason || "runner exiting");
+        await gatherSettled(...running.flatMap((entry) => (entry.runnerTask ? [entry.runnerTask] : [])));
+    }
+    /**
+     * Ask each root worker that has not finished to wind down.
+     *
+     * Both messages this takes end a worker, gracefully or not. A worker whose
+     * task has already finished is skipped; one that has not started yet has
+     * not finished either, so it is still told.
+     *
+     * Sending is all this does. The worker finishes in its own time, which is
+     * what the returned entries are for.
+     *
+     * @param messageClass The per-worker message to send.
+     * @param reason Optional human-readable reason, carried on each message.
+     * @returns The entries that were messaged, root or otherwise.
+     */
+    async _finishRunningWorkers(messageClass, reason) {
+        // A worker with no task has not started rather than finished, so it is
+        // still owed the message.
+        const running = [...this._entries.values()].filter((entry) => !entry.runnerTask?.done());
+        for (const entry of running) {
+            if (entry.worker.parent === null) {
+                await this._bus.send(new messageClass({ source: this.name, target: entry.worker.name, reason }));
+            }
+        }
+        return running;
+    }
+    /**
+     * Run `setup_worker_runner` from each file in `PIPECAT_SETUP_FILES`.
+     *
+     * A setup file may define `setup_worker_runner(runner)` (or `setupWorkerRunner`) to add workers,
+     * attach event handlers, or wire other runner-level configuration.
+     */
+    async _loadSetupFiles() {
+        await runSetupHook({ target: this, functionName: "setup_worker_runner" });
+    }
+    /** Run a registered worker as a background task. */
+    async _startWorker(entry) {
+        const worker = entry.worker;
+        logger.debug(`WorkerRunner '${this}': starting worker '${worker.name}'`);
+        entry.runnerTask = this.createTask(() => this._runWorker(worker), `task_${worker.name}`);
+        // Add the worker to event loop right away without needing to `await`.
+        await sleep(0);
+    }
+    /** Drive a registered worker to completion. */
+    async _runWorker(worker) {
+        try {
+            const params = new WorkerParams({ taskManager: this.taskManager });
+            await worker.run(params);
+        }
+        catch (e) {
+            if (!(e instanceof CancelledError))
+                throw e;
+        }
+        finally {
+            // End the runner once every root worker has finished. The current
+            // worker's task is still "running" (we're inside its body), so exclude
+            // it from the check.
+            if (this._autoEnd && worker.parent === null) {
+                const othersRunning = [...this._entries.values()].some((e) => e.worker.parent === null &&
+                    e.worker !== worker &&
+                    e.runnerTask !== null &&
+                    !e.runnerTask.done());
+                if (!othersRunning) {
+                    this._shutdownEvent.set();
+                }
+            }
+        }
+    }
+    /** Called when a local added worker registers as ready. */
+    async _onLocalWorkerReady(data) {
+        if (data.runner !== this.name) {
+            return;
+        }
+        const entry = this._entries.get(data.workerName);
+        if (!entry || entry.worker.parent !== null) {
+            return;
+        }
+        await this._sendRegistry();
+    }
+    /** Broadcast this runner's workers to the bus. */
+    async _sendRegistry() {
+        const workers = [...this._entries.values()].map((entry) => new WorkerRegistryEntry({
+            name: entry.worker.name,
+            parent: entry.worker.parent,
+            active: entry.worker.active,
+            bridged: entry.worker.bridged,
+            startedAt: entry.worker.startedAt,
+        }));
+        if (workers.length > 0) {
+            const names = workers.map((w) => w.name);
+            logger.debug(`WorkerRunner '${this}': broadcasting registry: [${names.map((n) => `'${n}'`).join(", ")}]`);
+            await this._bus.send(new BusWorkerRegistryMessage({
+                source: this.name,
+                runner: this.name,
+                workers,
+            }));
+        }
+    }
+    /** Handle a registry message from a remote runner. */
+    async _handleWorkerRegistry(message) {
+        const workerNames = message.workers.map((w) => w.name);
+        logger.debug(`WorkerRunner '${this}': received registry from '${message.runner}' ` +
+            `with workers: [${workerNames.map((n) => `'${n}'`).join(", ")}]`);
+        for (const entry of message.workers) {
+            await this._registry.register(new WorkerReadyData({ workerName: entry.name, runner: message.runner }));
+        }
+        if (!this._knownRunners.has(message.runner)) {
+            this._knownRunners.add(message.runner);
+            logger.debug(`WorkerRunner '${this}': new runner '${message.runner}', sending our registry back`);
+            await this._sendRegistry();
+        }
+    }
+    /**
+     * Set up SIGINT handler for graceful shutdown.
+     *
+     * DIVERGENCE: installed through the host's `process.on` when there is one
+     * (Bun, Node, Deno); a no-op on runtimes without process signals (Workers).
+     */
+    _setupSigint() {
+        signalProcess()?.on?.("SIGINT", () => this._sigHandler());
+    }
+    /**
+     * Set up SIGTERM handler for graceful shutdown.
+     *
+     * DIVERGENCE: see `_setupSigint`.
+     */
+    _setupSigterm() {
+        signalProcess()?.on?.("SIGTERM", () => this._sigHandler());
+    }
+    /** Handle interrupt signals by cancelling the runner. */
+    _sigHandler() {
+        if (!this._sigTask) {
+            this._sigTask = createTask(() => this._sigCancel());
+        }
+    }
+    /** Cancel the runner due to signal interruption. */
+    async _sigCancel() {
+        logger.warning(`WorkerRunner '${this}': interruption detected, cancelling.`);
+        await this.cancel("interrupt signal");
+    }
+    /**
+     * Force garbage collection and log results.
+     *
+     * DIVERGENCE: JS has no `gc.collect()` count or `gc.garbage`; this calls
+     * the global `gc()` when the runtime exposes one (e.g. Node/Deno with
+     * `--expose-gc`).
+     */
+    async _gcCollect() {
+        const gc = globalThis.gc;
+        if (typeof gc === "function") {
+            gc();
+            logger.debug("Garbage collector: collected.");
+        }
+        else {
+            logger.debug("Garbage collector: not exposed by this runtime, skipping.");
+        }
+    }
+    /** Warn about tasks left running on the task manager this runner owns. */
+    _printDanglingTasks() {
+        if (this._checkDanglingTasks) {
+            const tasks = this.taskManager.currentTasks().map((t) => t.getName());
+            if (tasks.length > 0) {
+                logger.warning(`${this} dangling tasks detected: [${tasks.map((t) => `'${t}'`).join(", ")}]`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/workers/ui/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * UI worker: an LLM worker that observes and drives a client GUI over RTVI.
+ *
+ * Composes the RTVI UI wire protocol (client events, accessibility snapshots,
+ * server UI commands) with `screenTools`, the tool a voice LLM uses to ask a
+ * `UIWorker` about the screen. `PipelineWorker` connects a `UIWorker` to the
+ * client automatically whenever RTVI is enabled — no decorator or separate
+ * component to wire up.
+ *
+ * Built-in UI command payload models (Toast, Navigate, ScrollTo, Highlight,
+ * Focus, Click, SetInputValue, SelectText) live in
+ * `processors/frameworks/rtvi/models`. Import them from there directly.
+ *
+ * Porting notes: the deprecated `BaseUIWorker` and `ReplyToolMixin`
+ * re-exports are not ported.
+ */
+export { BusUICommandMessage, BusUIEventMessage, BusUIJobCompletedMessage, BusUIJobGroupCompletedMessage, BusUIJobGroupStartedMessage, BusUIJobUpdateMessage, } from "../../bus/ui/messages.ts";
+export { uiEvent } from "./ui_event_decorator.ts";
+export { UI_STATE_PROMPT_GUIDE } from "./ui_prompts.ts";
+export { screenTools } from "./ui_tools.ts";
+export { UISelection, UIWorker } from "./ui_worker.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/workers/ui/index.js

@@ -0,0 +1,27 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/ui/__init__.py
+/**
+ * UI worker: an LLM worker that observes and drives a client GUI over RTVI.
+ *
+ * Composes the RTVI UI wire protocol (client events, accessibility snapshots,
+ * server UI commands) with `screenTools`, the tool a voice LLM uses to ask a
+ * `UIWorker` about the screen. `PipelineWorker` connects a `UIWorker` to the
+ * client automatically whenever RTVI is enabled — no decorator or separate
+ * component to wire up.
+ *
+ * Built-in UI command payload models (Toast, Navigate, ScrollTo, Highlight,
+ * Focus, Click, SetInputValue, SelectText) live in
+ * `processors/frameworks/rtvi/models`. Import them from there directly.
+ *
+ * Porting notes: the deprecated `BaseUIWorker` and `ReplyToolMixin`
+ * re-exports are not ported.
+ */
+export { BusUICommandMessage, BusUIEventMessage, BusUIJobCompletedMessage, BusUIJobGroupCompletedMessage, BusUIJobGroupStartedMessage, BusUIJobUpdateMessage, } from "../../bus/ui/messages.js";
+export { uiEvent } from "./ui_event_decorator.js";
+export { UI_STATE_PROMPT_GUIDE } from "./ui_prompts.js";
+export { screenTools } from "./ui_tools.js";
+export { UISelection, UIWorker } from "./ui_worker.js";
+//# sourceMappingURL=index.js.map

package/dist/workers/ui/ui_event_decorator.d.ts

@@ -0,0 +1,43 @@
+/** Decorator for marking worker methods as UI event handlers. */
+type AnyFn = (...args: any[]) => any;
+/** A function marked by `uiEvent()`. */
+export type UIEventHandler<F extends AnyFn = AnyFn> = F & {
+    isUiEventHandler: true;
+    uiEventName: string;
+};
+/**
+ * Mark a worker method as a handler for a named UI event.
+ *
+ * On `UIWorker` subclasses, decorated methods are automatically dispatched
+ * when a `BusUIEventMessage` with a matching `name` arrives.
+ *
+ * The returned decorator works both as a standard (TC39) method decorator and
+ * as a plain function, since runtimes that strip types (Node) do not run
+ * decorator syntax.
+ *
+ * @example
+ * class MyUIWorker extends UIWorker {
+ *   async onNav(message: BusUIEventMessage): Promise<void> {
+ *     const view = (message.payload as Record<string, unknown>).view;
+ *     ...
+ *   }
+ *   static {
+ *     uiEvent("nav_click")(this.prototype.onNav);
+ *   }
+ * }
+ *
+ * @param name The UI event name to match.
+ */
+export declare function uiEvent(name: string): <F extends AnyFn>(fn: F, _context?: unknown) => F;
+/**
+ * Collect all `uiEvent` decorated bound methods from an object.
+ *
+ * Walks the prototype chain so that overridden methods in subclasses take
+ * precedence over base-class definitions.
+ *
+ * @returns A map from event name to the bound method.
+ * @throws Error If two handlers share the same event name.
+ */
+export declare function _collectUiEventHandlers(obj: object): Map<string, AnyFn>;
+export {};
+//# sourceMappingURL=ui_event_decorator.d.ts.map

package/dist/workers/ui/ui_event_decorator.js

@@ -0,0 +1,75 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/ui/ui_event_decorator.py
+/**
+ * Mark a worker method as a handler for a named UI event.
+ *
+ * On `UIWorker` subclasses, decorated methods are automatically dispatched
+ * when a `BusUIEventMessage` with a matching `name` arrives.
+ *
+ * The returned decorator works both as a standard (TC39) method decorator and
+ * as a plain function, since runtimes that strip types (Node) do not run
+ * decorator syntax.
+ *
+ * @example
+ * class MyUIWorker extends UIWorker {
+ *   async onNav(message: BusUIEventMessage): Promise<void> {
+ *     const view = (message.payload as Record<string, unknown>).view;
+ *     ...
+ *   }
+ *   static {
+ *     uiEvent("nav_click")(this.prototype.onNav);
+ *   }
+ * }
+ *
+ * @param name The UI event name to match.
+ */
+export function uiEvent(name) {
+    return function decorator(fn, _context) {
+        const handler = fn;
+        handler.isUiEventHandler = true;
+        handler.uiEventName = name;
+        return fn;
+    };
+}
+/**
+ * Collect all `uiEvent` decorated bound methods from an object.
+ *
+ * Walks the prototype chain so that overridden methods in subclasses take
+ * precedence over base-class definitions.
+ *
+ * @returns A map from event name to the bound method.
+ * @throws Error If two handlers share the same event name.
+ */
+export function _collectUiEventHandlers(obj) {
+    const seen = new Set();
+    const handlers = new Map();
+    // event name -> defining method name, for errors
+    const sourceNames = new Map();
+    let proto = Object.getPrototypeOf(obj);
+    while (proto !== null && proto !== Object.prototype) {
+        for (const attrName of Object.getOwnPropertyNames(proto)) {
+            if (seen.has(attrName)) {
+                continue;
+            }
+            seen.add(attrName);
+            const descriptor = Object.getOwnPropertyDescriptor(proto, attrName);
+            // Skip accessors so collecting never runs a getter.
+            const val = descriptor && "value" in descriptor ? descriptor.value : undefined;
+            if (typeof val === "function" && val.isUiEventHandler === true) {
+                const eventName = val.uiEventName;
+                if (handlers.has(eventName)) {
+                    throw new Error(`Duplicate @ui_event handler for '${eventName}': ` +
+                        `'${attrName}' conflicts with '${sourceNames.get(eventName)}'`);
+                }
+                handlers.set(eventName, val.bind(obj));
+                sourceNames.set(eventName, attrName);
+            }
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    return handlers;
+}
+//# sourceMappingURL=ui_event_decorator.js.map

package/dist/workers/ui/ui_job_context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * User-facing job group context (compatibility shim).
+ *
+ * Porting notes:
+ * - Upstream this module holds only `UIJobGroupContext`, a deprecated alias
+ *   (since 1.8.0) for `JobGroupContext` with the historical constructor
+ *   signature. Deprecated upstream APIs are not ported, so this module is
+ *   intentionally empty: a group dispatched by a `UIWorker` is client-visible,
+ *   so use `JobGroupContext` (`worker.jobGroup(...)`) instead.
+ */
+export {};
+//# sourceMappingURL=ui_job_context.d.ts.map