@haywoodmarx/agent-pager 0.1.0

package/dist/src/tui/client.js

@@ -0,0 +1,279 @@
+import { connect } from "node:net";
+import { StringDecoder } from "node:string_decoder";
+import { OPERATOR_PROTOCOL_VERSION, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "../operator/protocol.js";
+import { validateOperatorCommandResultForCommand, validateOperatorCursor } from "../operator/validation.js";
+import { isPlainObject } from "../shared/guards.js";
+import { TuiOperatorTransportController } from "./transport.js";
+/** Bounds commands awaiting a result before the transport refuses more. */
+const PENDING_COMMAND_LIMIT = 32;
+/** Bounds observations buffered before a consumer attaches. */
+const BUFFERED_OBSERVATION_LIMIT = 32;
+/** Owns one cancellable loopback NDJSON session and exposes only model-guarded stream callbacks. */
+export class TuiOperatorTcpClient {
+    url;
+    #socket;
+    #buffer = "";
+    #controller;
+    #initial;
+    #receive;
+    #unavailable;
+    #observations = [];
+    #generation = 0;
+    #failed = false;
+    #failure;
+    #pendingCommands = new Map();
+    /**
+     * Construct a client for the published numeric loopback TCP endpoint. No connection opens until a fetch or open.
+     * @param url - Operator endpoint the broker published, naming a numeric loopback host and port.
+     */
+    constructor(url) {
+        this.url = url;
+    }
+    /**
+     * Open cold hydration and resolve exactly one authoritative snapshot.
+     * @returns Snapshot request; cancelling it resets the session, and a second fetch while one is pending rejects.
+     */
+    fetch() {
+        if (this.#initial)
+            return { promise: Promise.reject(new Error("TUI snapshot is already pending")), cancel: () => undefined };
+        this.#reset(false);
+        let cancelled = false;
+        let reject;
+        const promise = new Promise((resolve, rejectRequest) => {
+            reject = rejectRequest;
+            this.#initial = { resolve, reject: rejectRequest };
+            this.#connect(null);
+        });
+        return {
+            promise,
+            cancel: () => {
+                if (cancelled)
+                    return;
+                cancelled = true;
+                this.#reset(false);
+                reject(new Error("TUI snapshot cancelled"));
+            },
+        };
+    }
+    /**
+     * Attach the model-owned ordered callback, opening a resumed session when no socket is live.
+     *
+     * After hydration the session opened by `fetch` is already subscribed, and the cursor it was
+     * subscribed at is the one the caller now holds. Only a caller resuming without hydrating first
+     * reaches the connect below, and the cursor it supplies is what makes the server replay rather
+     * than transfer a whole snapshot.
+     * @param cursor - Position the caller already holds, or null when it holds no snapshot.
+     * @param receive - Receives each validated observation in stream order, including any buffered before this call.
+     * @param unavailable - Called once when the session fails; a failure recorded before this call is reported on the next microtask.
+     * @returns Cancellation callback for this stream generation.
+     */
+    open(cursor, receive, unavailable) {
+        this.#receive = receive;
+        this.#unavailable = unavailable;
+        if (this.#failure) {
+            const generation = this.#generation;
+            this.#failure = undefined;
+            queueMicrotask(() => unavailable());
+            return () => {
+                if (generation === this.#generation)
+                    this.#reset(false);
+            };
+        }
+        if (!this.#socket)
+            this.#connect(cursor);
+        const generation = this.#generation;
+        for (const observation of this.#observations.splice(0))
+            receive(observation);
+        return () => {
+            if (generation === this.#generation)
+                this.#reset(false);
+        };
+    }
+    /** Reset the current session. */
+    reconnect() {
+        this.#reset(false);
+    }
+    /**
+     * Submit one correlated non-authoritative command.
+     * @param command - Validated command envelope, correlated with its result by `commandId`.
+     * @returns Command request; it rejects at once without a live session, while hydration is pending, when
+     * too many commands are pending, or for a duplicate `commandId`, and rejects later if the session resets.
+     */
+    execute(command) {
+        if (!this.#socket || this.#initial || this.#pendingCommands.size >= PENDING_COMMAND_LIMIT)
+            return {
+                promise: Promise.reject(new Error("TUI operator command transport unavailable")),
+                cancel: () => undefined,
+            };
+        if (this.#pendingCommands.has(command.commandId))
+            return { promise: Promise.reject(new Error("TUI command is already pending")), cancel: () => undefined };
+        let reject;
+        const promise = new Promise((resolve, rejectRequest) => {
+            reject = rejectRequest;
+            this.#pendingCommands.set(command.commandId, { command, resolve, reject: rejectRequest });
+            this.#write({ type: "command", protocolVersion: OPERATOR_PROTOCOL_VERSION, command });
+        });
+        return {
+            promise,
+            cancel: () => {
+                if (this.#pendingCommands.delete(command.commandId))
+                    reject(new Error("TUI command cancelled"));
+            },
+        };
+    }
+    /** Release socket, input buffers, and all pending work exactly once. */
+    dispose() {
+        this.#reset(false, new Error("TUI operator transport disposed"));
+    }
+    #connect(cursor) {
+        this.#failed = false;
+        let endpoint;
+        try {
+            endpoint = new URL(this.url);
+            const port = Number(endpoint.port);
+            if (endpoint.protocol !== "tcp:" ||
+                !/^127(?:\.\d{1,3}){3}$/.test(endpoint.hostname) ||
+                !Number.isInteger(port) ||
+                port < 1 ||
+                port > 65_535)
+                throw new Error("TUI operator endpoint must be a numeric loopback TCP URL");
+        }
+        catch (cause) {
+            this.#fail(cause instanceof Error ? cause : new Error("TUI operator endpoint is invalid"));
+            return;
+        }
+        const generation = ++this.#generation;
+        const socket = connect({ host: endpoint.hostname, port: Number(endpoint.port) });
+        this.#socket = socket;
+        this.#controller = new TuiOperatorTransportController({
+            replace: (snapshot, replacement) => {
+                if (this.#initial) {
+                    const initial = this.#initial;
+                    this.#initial = undefined;
+                    initial.resolve(snapshot);
+                }
+                else
+                    this.#deliver({ type: "snapshot", snapshot, replacement });
+            },
+            event: (event) => {
+                this.#deliver({ type: "event", event });
+            },
+            recover: () => this.#deliver({ type: "resync" }),
+            incompatible: () => this.#deliver({ type: "incompatible" }),
+            diagnostic: (diagnostic) => this.#deliver({ type: "diagnostic", diagnostic }),
+            live: () => this.#deliver({ type: "live" }),
+            awaitReplacement: () => this.#deliver({ type: "resync_pending" }),
+            replacementProgress: () => this.#deliver({ type: "resync_progress" }),
+        });
+        socket.setEncoding("utf8");
+        socket.on("connect", () => {
+            if (generation === this.#generation)
+                this.#write(cursor
+                    ? { type: "subscribe", protocolVersion: OPERATOR_PROTOCOL_VERSION, cursor }
+                    : { type: "subscribe", protocolVersion: OPERATOR_PROTOCOL_VERSION });
+        });
+        const decoder = new StringDecoder("utf8");
+        socket.on("data", (chunk) => {
+            if (generation === this.#generation)
+                this.#receiveChunk(typeof chunk === "string" ? chunk : decoder.write(chunk));
+        });
+        socket.on("error", () => this.#fail(new Error("TUI operator transport unavailable"), generation));
+        socket.on("close", () => this.#fail(new Error("TUI operator transport unavailable"), generation));
+    }
+    #receiveChunk(chunk) {
+        this.#buffer += chunk;
+        for (;;) {
+            const newline = this.#buffer.indexOf("\n");
+            if (newline < 0) {
+                if (Buffer.byteLength(this.#buffer) > OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES)
+                    this.#fail(new Error("TUI operator frame exceeds limit"));
+                return;
+            }
+            const line = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (Buffer.byteLength(line) > OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES)
+                return this.#fail(new Error("TUI operator frame exceeds limit"));
+            try {
+                const frame = JSON.parse(line);
+                if (!isPlainObject(frame))
+                    return this.#fail(new Error("TUI operator frame is invalid"));
+                if (frame.type === "command_result") {
+                    if (Object.keys(frame).length !== 2 || !("result" in frame))
+                        return this.#fail(new Error("TUI command result frame is invalid"));
+                    this.#receiveCommandResult(frame.result);
+                }
+                else {
+                    this.#controller?.receive(frame);
+                    // Validated before it is echoed back in an ack.
+                    if (frame.type === "heartbeat" && frame.cursor !== undefined)
+                        this.#write({
+                            type: "ack",
+                            protocolVersion: OPERATOR_PROTOCOL_VERSION,
+                            cursor: validateOperatorCursor(frame.cursor),
+                        });
+                }
+            }
+            catch {
+                return this.#fail(new Error("TUI operator frame is invalid"));
+            }
+        }
+    }
+    #receiveCommandResult(value) {
+        if (typeof value !== "object" || value === null || !("commandId" in value) || typeof value.commandId !== "string")
+            return this.#fail(new Error("TUI command result is invalid"));
+        const pending = this.#pendingCommands.get(value.commandId);
+        if (!pending)
+            return this.#fail(new Error("TUI command result is unexpected"));
+        try {
+            const result = validateOperatorCommandResultForCommand(pending.command, value);
+            this.#pendingCommands.delete(value.commandId);
+            pending.resolve(result.result);
+        }
+        catch {
+            this.#fail(new Error("TUI command result is invalid"));
+        }
+    }
+    #write(value) {
+        this.#socket?.write(`${JSON.stringify(value)}\n`);
+    }
+    #fail(error, generation = this.#generation) {
+        if (generation !== this.#generation || this.#failed)
+            return;
+        this.#failed = true;
+        this.#failure = error;
+        const initial = this.#initial;
+        const unavailable = this.#unavailable;
+        this.#reset(true);
+        initial?.reject(error);
+        unavailable?.();
+    }
+    #reset(keepFailure, commandError = new Error("TUI operator transport unavailable")) {
+        ++this.#generation;
+        this.#socket?.destroy();
+        this.#socket = undefined;
+        this.#buffer = "";
+        this.#controller = undefined;
+        this.#initial = undefined;
+        this.#receive = undefined;
+        this.#unavailable = undefined;
+        this.#observations = [];
+        this.#rejectPendingCommands(commandError);
+        if (!keepFailure) {
+            this.#failed = false;
+            this.#failure = undefined;
+        }
+    }
+    #rejectPendingCommands(error) {
+        for (const pending of this.#pendingCommands.values())
+            pending.reject(error);
+        this.#pendingCommands.clear();
+    }
+    #deliver(observation) {
+        if (this.#receive)
+            this.#receive(observation);
+        else if (this.#observations.length < BUFFERED_OBSERVATION_LIMIT)
+            this.#observations.push(observation);
+        else
+            this.#fail(new Error("TUI operator observations exceed limit"));
+    }
+}

package/dist/src/tui/composition.d.ts

@@ -0,0 +1,41 @@
+import type { EventEmitter } from "node:events";
+import { type CliRenderer, type CliRendererConfig } from "@opentui/core";
+import type { ReactNode } from "react";
+import { type TuiExitSignal, type TuiProcessPort, type TuiRuntime } from "./runtime.js";
+/** Renderer settings that cannot override application-owned shutdown policy. */
+export type OpenTuiRendererOptions = Omit<CliRendererConfig, "exitOnCtrlC" | "exitSignals" | "onDestroy" | "openConsoleOnError">;
+/** Configuration accepted by the production OpenTUI composition root. */
+export type OpenTuiRuntimeOptions = {
+    /** Non-lifecycle renderer configuration. */
+    renderer?: OpenTuiRendererOptions;
+    /** Signals routed through orderly renderer shutdown. */
+    exitSignals?: readonly TuiExitSignal[];
+    /** Process lifecycle adapter; defaults to the current Bun process. */
+    process?: TuiProcessPort;
+};
+/**
+ * Adapt a Bun process to the lifecycle port used by the TUI consumer.
+ * @param processObject - Bun-hosted process whose listeners and exit belong to this application.
+ * @returns Process port with removable listeners and conventional signal statuses.
+ */
+export declare function createBunTuiProcessPort(processObject?: NodeJS.Process): TuiProcessPort;
+/**
+ * Isolate failures from the listener set present when the renderer dispatches its destroy event.
+ * @param renderer - Event source whose destroy dispatch is guarded without changing other events.
+ * @param reportError - Sink receiving each dispatch failure without interrupting later subscribers.
+ */
+export declare function installOpenTuiDestroyEmissionGuard(renderer: EventEmitter, reportError: (error: unknown) => void): void;
+/**
+ * Compose the Bun-owned renderer, React reconciler, process lifecycle, and application node.
+ * @param node - React presentation tree mounted into the terminal renderer.
+ * @param options - Renderer tuning and configured application signals.
+ * @returns Running OpenTUI runtime with an orderly shutdown entry point.
+ */
+export declare function startOpenTui(node: ReactNode, options?: OpenTuiRuntimeOptions): Promise<TuiRuntime<CliRenderer>>;
+/**
+ * Compose a terminal tree after the runtime has supplied its single shutdown entry point.
+ * @param createNode - Factory receiving the idempotent orderly-shutdown action.
+ * @param options - Renderer tuning and configured application signals.
+ * @returns Running OpenTUI runtime with an orderly shutdown entry point.
+ */
+export declare function startOpenTuiFactory(createNode: (shutdown: TuiRuntime<CliRenderer>["shutdown"]) => ReactNode, options?: OpenTuiRuntimeOptions): Promise<TuiRuntime<CliRenderer>>;

package/dist/src/tui/composition.js

@@ -0,0 +1,146 @@
+import { constants } from "node:os";
+import { writeSync } from "node:fs";
+import { createCliRenderer } from "@opentui/core";
+import { createRoot, flushSync } from "@opentui/react";
+import { DEFAULT_TUI_EXIT_SIGNALS, startTuiRuntime, } from "./runtime.js";
+/** Offsets a signal number into the exit code a shell reports for a signalled process. */
+const SIGNAL_EXIT_CODE_OFFSET = 128;
+/**
+ * Adapt a Bun process to the lifecycle port used by the TUI consumer.
+ * @param processObject - Bun-hosted process whose listeners and exit belong to this application.
+ * @returns Process port with removable listeners and conventional signal statuses.
+ */
+export function createBunTuiProcessPort(processObject = process) {
+    return {
+        onSignal(signal, listener) {
+            processObject.on(signal, listener);
+            return () => processObject.removeListener(signal, listener);
+        },
+        onUncaughtException(listener) {
+            const processListener = (error) => {
+                listener(error);
+            };
+            processObject.on("uncaughtException", processListener);
+            return () => processObject.removeListener("uncaughtException", processListener);
+        },
+        onUnhandledRejection(listener) {
+            const processListener = (error) => {
+                listener(error);
+            };
+            processObject.on("unhandledRejection", processListener);
+            return () => processObject.removeListener("unhandledRejection", processListener);
+        },
+        signalExitCode(signal) {
+            return SIGNAL_EXIT_CODE_OFFSET + constants.signals[signal];
+        },
+        report(line) {
+            // Process exit follows immediately, so this write must complete before returning.
+            try {
+                writeSync(processObject.stderr.fd, `${line}\n`);
+            }
+            catch {
+                processObject.stderr.write(`${line}\n`);
+            }
+        },
+        exit(exitCode) {
+            processObject.exit(exitCode);
+        },
+    };
+}
+/**
+ * Isolate failures from the listener set present when the renderer dispatches its destroy event.
+ * @param renderer - Event source whose destroy dispatch is guarded without changing other events.
+ * @param reportError - Sink receiving each dispatch failure without interrupting later subscribers.
+ */
+export function installOpenTuiDestroyEmissionGuard(renderer, reportError) {
+    // OpenTUI has no destroy listeners when createCliRenderer resolves. This hook runs then, before
+    // React registers its cleanup through once(), so every production once wrapper is observed.
+    const onceWrappers = new WeakSet();
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Borrowed EventEmitter calls require the caller's receiver.
+    const emit = renderer.emit;
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Destroy snapshots belong to the caller's receiver.
+    const rawListenersFor = renderer.rawListeners;
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Registration must retain the caller's receiver.
+    const once = renderer.once;
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- Registration must retain the caller's receiver.
+    const prependOnceListener = renderer.prependOnceListener;
+    const recordOnceWrapper = (receiver, event, index) => {
+        if (event !== "destroy")
+            return;
+        const rawListeners = Reflect.apply(rawListenersFor, receiver, [event]);
+        const rawListener = rawListeners.at(index);
+        if (rawListener)
+            onceWrappers.add(rawListener);
+    };
+    renderer.once = function (...parameters) {
+        const result = Reflect.apply(once, this, parameters);
+        recordOnceWrapper(this, parameters[0], -1);
+        return result;
+    };
+    renderer.prependOnceListener = function (...parameters) {
+        const result = Reflect.apply(prependOnceListener, this, parameters);
+        recordOnceWrapper(this, parameters[0], 0);
+        return result;
+    };
+    renderer.emit = function (event, ...arguments_) {
+        if (event !== "destroy")
+            return Reflect.apply(emit, this, [event, ...arguments_]);
+        const rawListeners = Reflect.apply(rawListenersFor, this, [event]);
+        if (rawListeners.length === 0)
+            return false;
+        for (const rawListener of rawListeners) {
+            try {
+                Reflect.apply(rawListener, this, arguments_);
+            }
+            catch (error) {
+                reportError(error);
+                if (onceWrappers.has(rawListener)) {
+                    try {
+                        Reflect.apply(rawListener, this, arguments_);
+                    }
+                    catch (retryError) {
+                        reportError(retryError);
+                    }
+                }
+            }
+        }
+        return true;
+    };
+}
+/**
+ * Compose the Bun-owned renderer, React reconciler, process lifecycle, and application node.
+ * @param node - React presentation tree mounted into the terminal renderer.
+ * @param options - Renderer tuning and configured application signals.
+ * @returns Running OpenTUI runtime with an orderly shutdown entry point.
+ */
+export function startOpenTui(node, options = {}) {
+    return startOpenTuiFactory(() => node, options);
+}
+/**
+ * Compose a terminal tree after the runtime has supplied its single shutdown entry point.
+ * @param createNode - Factory receiving the idempotent orderly-shutdown action.
+ * @param options - Renderer tuning and configured application signals.
+ * @returns Running OpenTUI runtime with an orderly shutdown entry point.
+ */
+export function startOpenTuiFactory(createNode, options = {}) {
+    if (typeof Bun === "undefined")
+        throw new Error("The OpenTUI runtime requires Bun");
+    const rendererOptions = options.renderer ?? {};
+    return startTuiRuntime({
+        createRenderer: (lifecycleOptions) => createCliRenderer({ ...rendererOptions, ...lifecycleOptions }),
+        mount(renderer, shutdown) {
+            const root = createRoot(renderer);
+            root.render(createNode(shutdown));
+            return {
+                dispose() {
+                    flushSync(() => {
+                        root.unmount();
+                    });
+                },
+            };
+        },
+        prepareRenderer: installOpenTuiDestroyEmissionGuard,
+        process: options.process ?? createBunTuiProcessPort(),
+        exitSignals: options.exitSignals ?? DEFAULT_TUI_EXIT_SIGNALS,
+    });
+}

package/dist/src/tui/message-views.d.ts

@@ -0,0 +1,94 @@
+import { useRenderer } from "@opentui/react";
+import { type OperatorAcceptedDelivery, type OperatorCommandResult, type OperatorTraffic } from "../operator/protocol.js";
+import type { TuiOperatorModel } from "./model.js";
+import type { TuiTheme } from "./theme.js";
+/** Reads public full-body content without giving a renderer access to broker storage. */
+export interface TuiMessageBodyPort {
+    read(message: OperatorAcceptedDelivery): TuiMessageBodyView;
+}
+/** Separates rendered public content from the exact raw-copy representation. */
+export type TuiMessageBodyView = {
+    readonly display: string;
+    readonly rawCopy: string;
+};
+/** Reports whether a raw-copy request reached the terminal or a native fallback. */
+export type TuiCopyResult = "osc52" | "copied" | "unavailable";
+/** Handles a copy request the current terminal cannot safely perform through OSC52. */
+export interface TuiCopyFallbackPort {
+    copyUnavailable(rawCopy: string): Extract<TuiCopyResult, "copied" | "unavailable">;
+}
+/** Creates unique command correlations and records command-result observation. */
+export interface TuiMessageCommandPort {
+    commandId(): string;
+    /** Epoch milliseconds a command is stamped with when it is issued. */
+    issuedAt(): number;
+    observe(result: OperatorCommandResult): void;
+}
+/** Shared explicit dependencies for message presentation. */
+export type MessageViewsProps = {
+    readonly model: TuiOperatorModel;
+    readonly theme: Readonly<TuiTheme>;
+    readonly body: TuiMessageBodyPort;
+    readonly copyFallback: TuiCopyFallbackPort;
+    readonly commands: TuiMessageCommandPort;
+    readonly colorEnabled?: boolean;
+};
+/**
+ * Render a distinct, renderer-neutral description for each traffic protocol member.
+ * @param entry - Traffic row of either member; identities are printed raw rather than as handles.
+ * @returns One line giving a delivery's state glyph, endpoints and message id, or an audit's glyph, target and the word ping.
+ */
+export declare function formatTuiTraffic(entry: OperatorTraffic): string;
+/**
+ * Move the agent-log selection one row without wrapping past either end.
+ * @param model - Model owning the local view state.
+ * @param direction - Row step the operator asked for.
+ * @returns Whether the log consumed the step.
+ */
+export declare function stepTuiTrafficSelection(model: TuiOperatorModel, direction: "up" | "down"): boolean;
+/**
+ * Select the newest row of the agent log for an operator arriving with nothing chosen.
+ *
+ * Follow is turned on rather than preserved: the selection lands on the tail, so the operator is at
+ * the position follow tracks and has not scrolled away from it.
+ * @param model - Operator model whose view selection is advanced.
+ * @returns Whether a row was available to select.
+ */
+export declare function selectNewestTuiTraffic(model: TuiOperatorModel): boolean;
+/**
+ * Render traffic rows and keep tail-follow state behind the model boundary.
+ * @param properties - Model, palette, whether agents are coloured, and the pane's columns.
+ * @returns A column heading over scrolling rows, or over a placeholder when the selection scopes no traffic.
+ */
+export declare function AgentTrafficLog({ model, theme, colorEnabled, width, }: Pick<MessageViewsProps, "model" | "theme" | "colorEnabled"> & {
+    readonly width?: number;
+}): import("react").ReactNode;
+/**
+ * Render the selected accepted delivery's metadata, lifecycle, scrolling body, and full-body affordance.
+ * @param properties - Model, palette, body reader, whether agents are coloured, the pane's columns, and the rows the body block takes, including its subject and spacer rows.
+ * @returns The message log pane content, or a placeholder when no delivery is selected.
+ */
+export declare function MessageDetail({ model, theme, body, colorEnabled, width: paneWidth, bodyRows, }: Pick<MessageViewsProps, "model" | "theme" | "body" | "colorEnabled"> & {
+    readonly width?: number;
+    readonly bodyRows?: number;
+}): import("react").ReactNode;
+/**
+ * Render the full-body, message context, and expire confirmation overlays at the terminal root.
+ * @param properties - Model whose overlay state chooses what renders, and the body, copy and command ports the overlays use.
+ * @returns The open message overlay, or nothing when the open overlay is not a message overlay or its message has left the projection.
+ */
+export declare function MessageOverlays(properties: MessageViewsProps): import("react").ReactNode;
+/**
+ * Actions the message context menu offers, in display order.
+ *
+ * An index that names none of them does nothing.
+ */
+export declare const MESSAGE_CONTEXT_ACTIONS: readonly ["open", "copy", "expire"];
+/**
+ * Guard OSC52 with OpenTUI's exact capability probe before emitting a clipboard sequence.
+ * @param renderer - Renderer whose capability probe and OSC52 write are used.
+ * @param rawCopy - Exact text to place on the clipboard.
+ * @param fallback - Native copy used when the terminal cannot take OSC52 or the write fails.
+ * @returns How the copy was performed, or that it could not be.
+ */
+export declare function copyRaw(renderer: Pick<ReturnType<typeof useRenderer>, "isOsc52Supported" | "copyToClipboardOSC52">, rawCopy: string, fallback: TuiCopyFallbackPort): TuiCopyResult;