@tx5dr/plugin-api 1.7.12 → 2.0.0

package/dist/helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ParsedFT8Message, SlotInfo, SlotPack, QSORecord, FrameMessage, OperatorSlots, ModeDescriptor, EngineMode, PermissionGrant, PluginPanelDescriptor, CapabilityList, CapabilityState, RadioPowerResponse, RadioPowerStateEvent, RadioPowerSupportInfo, RadioPowerTarget, WriteCapabilityPayload } from '@tx5dr/contracts';
+import type { ParsedFT8Message, SlotInfo, SlotPack, FrameMessage, ModeDescriptor, EngineMode, PermissionGrant, PluginPanelDescriptor, CapabilityList, CapabilityState, RadioPowerResponse, RadioPowerStateEvent, RadioPowerSupportInfo, RadioPowerTarget } from '@tx5dr/contracts';
 import type { StrategyRuntimeSnapshot } from './runtime.js';
 /**
  * Simple persistent key-value store exposed to plugins.
@@ -10,11 +10,17 @@ export interface KVStore {
     /**
      * Reads a stored value.
      *
-     * When the key is missing, the provided `defaultValue` is returned instead.
+     * Stored values are returned by value, so mutating the result does not update
+     * persistence until {@link set} is called. When the key is missing, the
+     * caller-owned `defaultValue` is returned unchanged.
      */
     get<T = unknown>(key: string, defaultValue?: T): T;
     /**
-     * Persists a value under the given key.
+     * Persists a JSON-compatible snapshot under the given key.
+     *
+     * `undefined` follows JSON object semantics and removes the key. Cycles,
+     * BigInt values, functions and Host capabilities are rejected with
+     * `PLUGIN_DATA_NOT_SERIALIZABLE`.
      */
     set(key: string, value: unknown): void;
     /**
@@ -22,7 +28,7 @@ export interface KVStore {
      */
     delete(key: string): void;
     /**
-     * Returns a shallow snapshot of all stored entries in this scope.
+     * Returns an independent snapshot of all stored entries in this scope.
      */
     getAll(): Record<string, unknown>;
     /**
@@ -70,40 +76,134 @@ export interface PluginTimers {
  * Remote UDP endpoint metadata for datagrams received by plugin-owned sockets.
  */
 export interface PluginUdpRemoteInfo {
+    /** Source IP address reported by the UDP socket. */
     address: string;
+    /** Source UDP port. */
     port: number;
+    /** Address family reported by Node.js, typically `IPv4` or `IPv6`. */
     family: string;
+    /** Datagram size in bytes. */
     size: number;
 }
+/** Local endpoint used when binding a plugin-owned UDP socket. */
 export interface PluginUdpBindOptions {
+    /** Local interface/address. Omit to use the Host default. */
     host?: string;
+    /** Local port. Omit or use `0` to let the operating system choose one. */
     port?: number;
 }
+/** Options applied when the Host creates a plugin-owned UDP socket. */
 export interface PluginUdpSocketOptions {
+    /** IP family. Defaults to `udp4`. */
     type?: 'udp4' | 'udp6';
+    /** Whether multiple sockets may reuse the local address. */
     reuseAddr?: boolean;
+    /** Whether the socket may send IPv4 broadcast datagrams. */
     broadcast?: boolean;
+    /** Multicast time-to-live applied to outbound multicast packets. */
     multicastTtl?: number;
 }
+/**
+ * Host-owned UDP socket capability.
+ *
+ * The handle may be stored by the plugin, but its methods are invocation
+ * guarded. Close it during unload when possible; Host cleanup also closes all
+ * sockets owned by the plugin instance.
+ */
 export interface PluginUdpSocket {
+    /** Binds the socket and resolves when it is ready to receive datagrams. */
     bind(options?: PluginUdpBindOptions): Promise<void>;
+    /** Sends one datagram to the exact remote host and port. */
     send(data: Uint8Array | string, port: number, host: string): Promise<void>;
+    /** Registers the callback used for received datagrams. */
     onMessage(handler: (data: Uint8Array, remote: PluginUdpRemoteInfo) => void | Promise<void>): void;
+    /** Registers the callback used for socket-level errors. */
     onError(handler: (error: Error) => void): void;
+    /** Closes the socket. Calling it again is safe. */
     close(): Promise<void>;
 }
+/** Factory and bulk-cleanup surface for UDP sockets owned by one plugin instance. */
 export interface PluginUdpControl {
+    /** Creates an unbound socket with the requested options. */
     createSocket(options?: PluginUdpSocketOptions): PluginUdpSocket;
+    /** Closes every UDP socket created through this control. */
     closeAll(): Promise<void>;
 }
+/** Network capability exposed when the plugin declares `network`. */
 export interface PluginNetworkControl {
+    /** UDP socket factory. HTTP requests use the sibling `ctx.fetch` capability. */
     readonly udp: PluginUdpControl;
 }
 /**
- * Control surface for the active operator instance.
+ * A message delivered through the plugin-to-plugin event bus.
+ *
+ * Every message carries metadata about its publisher so subscribers can
+ * apply routing or filtering logic based on the source plugin.
+ */
+export interface PluginEventBusMessage {
+    /** The topic this message was published to. */
+    topic: string;
+    /**
+     * Structured-clone-compatible payload. The host does not interpret its
+     * business schema, but delivers an independent value to each subscriber.
+     */
+    payload: unknown;
+    /** Epoch milliseconds when the host dispatched the message. */
+    timestamp: number;
+    /** Identity of the plugin instance that published this message. */
+    publisher: {
+        /** Name of the publishing plugin (from its `PluginDefinition.name`). */
+        pluginName: string;
+        /** Whether the publisher is a global or per-operator instance. */
+        instanceScope: 'operator' | 'global';
+        /** Operator ID when the publisher is an operator-scoped instance. */
+        operatorId?: string;
+    };
+}
+/**
+ * Permission-gated pub/sub bus for in-process plugin-to-plugin communication.
+ *
+ * Topics are plain strings shared across all plugin instances within the same
+ * host process. Handlers are started synchronously in subscription order.
+ * Async handlers run independently; their errors are captured and logged by
+ * the host rather than propagated to the publisher.
+ *
+ * **Lifecycle**: the host automatically removes all subscriptions owned by a
+ * plugin instance when it unloads. Individual subscriptions can be cancelled
+ * earlier by calling the function returned from {@link subscribe}.
  *
- * This interface lets plugins inspect operator state and request host-managed
- * actions such as starting automation, calling a target or notifying the UI.
+ * **Topic naming**: use dot-separated, plugin-prefixed names to avoid
+ * collisions — for example `my-plugin.status.changed` or
+ * `callsign-filter.match.found`.
+ */
+export interface PluginEventBus {
+    /**
+     * Publishes a message to all current subscribers of the given topic.
+     *
+     * This is a fire-and-forget operation. The host guarantees that subscriber
+     * exceptions never propagate back to the caller. The call itself throws
+     * synchronously when the payload is not structured-clone compatible or
+     * contains a Host capability.
+     *
+     * @param topic - Exact topic string to publish to.
+     * @param payload - Optional structured-clone-compatible data. Keep payloads reasonably small.
+     */
+    publish(topic: string, payload?: unknown): void;
+    /**
+     * Subscribes to messages on the given topic.
+     *
+     * The same handler function instance will only be added once per topic.
+     * Different closures with identical logic are treated as distinct subscribers.
+     *
+     * @param topic - Exact topic string to listen on.
+     * @param handler - Callback invoked for each matching message. May return a
+     *   `Promise`; the host catches rejections and logs them.
+     * @returns An unsubscribe function. Calling it more than once is a no-op.
+     */
+    subscribe(topic: string, handler: (message: PluginEventBusMessage) => void | Promise<void>): () => void;
+}
+/**
+ * Read-only summary of another operator in the same Host.
  */
 export interface OtherOperatorSnapshot {
     /** Unique operator identifier used by the host. */
@@ -120,8 +220,15 @@ export interface OtherOperatorSnapshot {
     readonly isTransmitting: boolean;
     /** Current transmit cycle selection where `0` is even and `1` is odd. */
     readonly transmitCycles: number[];
+    /** Current automation runtime snapshot when available. */
+    readonly automation?: StrategyRuntimeSnapshot | null;
 }
-export interface OperatorControl {
+/**
+ * Read-only state and query surface for the current operator-scoped plugin
+ * instance. Mutations are submitted through `ctx.operatorCommands` when the
+ * plugin declares `operator:transmit-control`.
+ */
+export interface OperatorSnapshot {
     /** Unique operator identifier used by the host. */
     readonly id: string;
     /** Whether this operator is currently transmitting or otherwise armed. */
@@ -140,39 +247,6 @@ export interface OperatorControl {
     readonly automation: StrategyRuntimeSnapshot | null;
     /** Returns read-only snapshots for operators other than the current instance. */
     getOtherOperators(): OtherOperatorSnapshot[];
-    /** Enables transmission/automation for the current operator. */
-    startTransmitting(): void;
-    /** Disables transmission/automation for the current operator. */
-    stopTransmitting(): void;
-    /**
-     * Requests that the operator call the specified target station.
-     *
-     * Passing `lastMessage` helps the host preserve the triggering context.
-     */
-    call(callsign: string, lastMessage?: {
-        message: FrameMessage;
-        slotInfo: SlotInfo;
-    }): void;
-    /**
-     * Requests host-managed reply behavior for a decoded message.
-     *
-     * This is equivalent to an operator selecting a decode in the RX view while
-     * keeping the API independent from any specific UDP/control protocol.
-     */
-    replyToDecode(decode: {
-        callsign: string;
-        lastMessage: {
-            message: FrameMessage;
-            slotInfo: SlotInfo;
-        };
-        modifiers?: number;
-    }): void;
-    /**
-     * Updates the operator's transmit cycle preference.
-     *
-     * Pass a single value or an array to support alternating or multi-cycle modes.
-     */
-    setTransmitCycles(cycles: number | number[]): void;
     /**
      * Checks whether this operator has previously worked the given callsign.
      */
@@ -184,40 +258,81 @@ export interface OperatorControl {
      * working the target callsign.
      */
     isTargetBeingWorkedByOthers(targetCallsign: string): boolean;
-    /** Clears host-managed decoded-message views when available. */
-    clearDecodes(window?: number): void;
-    /** Stops current transmission/automation. */
-    haltTransmission(options?: {
-        autoOnly?: boolean;
-    }): void;
-    /** Stores the current free-text message without necessarily transmitting it. */
-    setFreeText(text: string): void;
-    /** Requests transmission of free text. If text is provided it is stored first. */
-    sendFreeText(text?: string): void;
-    /** Applies a temporary session grid/location override when the host supports it. */
-    setTemporaryLocation(location: string): void;
-    /** Requests callsign highlighting in host decode views when available. */
-    highlightCallsign(rule: {
-        callsign: string;
-        background?: string | null;
-        foreground?: string | null;
-        lastOnly?: boolean;
-    }): void;
-    /**
-     * Records a completed QSO through the host logbook pipeline.
-     */
-    recordQSO(record: QSORecord): void;
-    /**
-     * Pushes updated slot text content to the frontend operator view.
-     */
-    notifySlotsUpdated(slots: OperatorSlots): void;
-    /**
-     * Pushes a strategy state change notification to the frontend operator view.
-     */
-    notifyStateChanged(state: string): void;
 }
 /**
- * Read/write access to radio state that is safe for plugins.
+ * Declarative operator mutations accepted by the host transmission framework.
+ *
+ * The command set deliberately contains no PTT, audio, mixer, encoder, raw
+ * transmit or emergency-stop primitive. Plugins can request product actions;
+ * only the host coordinators may translate them into a physical RF lifecycle.
+ */
+export type PluginOperatorCommand = {
+    type: 'start-automation';
+} | {
+    type: 'stop-automation';
+} | {
+    type: 'request-call';
+    callsign: string;
+    lastMessage?: {
+        message: FrameMessage;
+        slotInfo: SlotInfo;
+    };
+} | {
+    type: 'reply-to-decode';
+    callsign: string;
+    lastMessage: {
+        message: FrameMessage;
+        slotInfo: SlotInfo;
+    };
+    modifiers?: number;
+} | {
+    type: 'set-transmit-cycles';
+    cycles: number | number[];
+} | {
+    type: 'remove-contribution';
+} | {
+    type: 'clear-decodes';
+    window?: number;
+} | {
+    type: 'set-free-text';
+    text: string;
+} | {
+    type: 'send-free-text';
+    text?: string;
+} | {
+    type: 'set-temporary-location';
+    location: string;
+} | {
+    type: 'highlight-callsign';
+    callsign: string;
+    background?: string | null;
+    foreground?: string | null;
+    lastOnly?: boolean;
+};
+/** Settlement returned after the Host accepts an operator command. */
+export interface PluginOperatorCommandResult {
+    /** Host command epoch allocated before any asynchronous work begins. */
+    epoch: number;
+    /** `superseded` means a newer host command revoked this request. */
+    outcome: 'completed' | 'superseded';
+}
+/**
+ * Capability-scoped command port for plugins with
+ * `operator:transmit-control` and API v2.
+ *
+ * The property is omitted from contexts without that capability. Every submit
+ * is invocation-guarded and enters the host's per-operator intent lane.
+ */
+export interface OperatorCommandPort {
+    /**
+     * Submits one high-level operator command through the Host intent lane.
+     * Rejects when the invocation expired, the plugin safety gate is disabled,
+     * or the current physical lifecycle cannot accept the command.
+     */
+    submit(command: PluginOperatorCommand): Promise<PluginOperatorCommandResult>;
+}
+/**
+ * Read-only operating-mode projection that is safe for plugins.
  */
 export interface RadioOperatingMode {
     /**
@@ -241,7 +356,8 @@ export interface RadioOperatingMode {
      */
     readonly descriptor: ModeDescriptor;
 }
-export interface RadioControl {
+/** Read-only frequency, band, mode and connection state for the active radio. */
+export interface RadioView {
     /** Current tuned radio frequency in Hz. */
     readonly frequency: number;
     /** Human-readable current band label, for example `20m`. */
@@ -250,31 +366,52 @@ export interface RadioControl {
     readonly mode: RadioOperatingMode;
     /** Whether the radio transport is currently connected. */
     readonly isConnected: boolean;
-    /** Negotiated radio capability controls. Requires radio plugin permissions. */
-    readonly capabilities: RadioCapabilitiesControl;
-    /** Physical radio power controls. Requires radio plugin permissions. */
-    readonly power: RadioPowerControl;
-    /**
-     * Requests a frequency change.
-     *
-     * The host remains responsible for serializing hardware access and enforcing
-     * any safety or capability constraints.
-     */
-    setFrequency(freq: number): Promise<void>;
 }
 /**
  * Access to the host-managed radio capability negotiation system.
  */
-export interface RadioCapabilitiesControl {
-    /** Returns the current capability descriptor/state snapshot. Requires `radio:read`. */
+export interface RadioCapabilitiesView {
+    /** Returns the current capability descriptor/state snapshot. */
     getSnapshot(): CapabilityList;
-    /** Returns a single capability state from the current snapshot, or null. Requires `radio:read`. */
+    /** Returns a single capability state from the current snapshot, or null. */
     getState(id: string): CapabilityState | null;
-    /** Refreshes readable capability values and returns the updated snapshot. Requires `radio:read`. */
+    /** Refreshes readable capability values and returns the updated snapshot. */
     refresh(): Promise<CapabilityList>;
-    /** Writes a capability value or triggers an action capability. Requires `radio:control`. */
-    write(payload: WriteCapabilityPayload): Promise<void>;
 }
+/** Declarative radio mutations accepted by the host radio coordinator. */
+export type PluginRadioCommand = {
+    type: 'set-frequency';
+    frequency: number;
+} | {
+    /** Atomically changes band and optionally starts the radio's tuner while RF is idle. */
+    type: 'switch-band';
+    frequency: number;
+    autoTune?: boolean;
+};
+/**
+ * Capability-scoped radio command port.
+ *
+ * This port exists only for plugins with `radio:control`. It deliberately does
+ * not expose a radio connection, PTT primitive, mode switch, audio output or
+ * any other physical device object.
+ */
+export interface RadioCommandPort {
+    /** Submits a frequency/band command after Host physical-idle validation. */
+    submit(command: PluginRadioCommand): Promise<void>;
+}
+/** Explicit tuner operations; no arbitrary capability identifier is accepted. */
+export type PluginRadioTunerCommand = {
+    type: 'set-enabled';
+    enabled: boolean;
+} | {
+    type: 'start-manual-tune';
+};
+/** Capability-scoped tuner command port for `radio:tuner-control` plugins. */
+export interface RadioTunerCommandPort {
+    /** Submits one explicit tuner operation after Host safety validation. */
+    submit(command: PluginRadioTunerCommand): Promise<void>;
+}
+/** Optional target profile and startup behavior for a radio power command. */
 export interface RadioPowerSetOptions {
     /** Profile to target. Defaults to the active profile. */
     profileId?: string;
@@ -284,13 +421,25 @@ export interface RadioPowerSetOptions {
 /**
  * Access to physical radio power management.
  */
-export interface RadioPowerControl {
-    /** Returns power support information for the active or specified profile. Requires `radio:read`. */
+export interface RadioPowerView {
+    /** Returns power support information for the active or specified profile. */
     getSupport(profileId?: string): Promise<RadioPowerSupportInfo>;
-    /** Returns the last known power transition state for the active or specified profile. Requires `radio:read`. */
+    /** Returns the last known power transition state for the active or specified profile. */
     getState(profileId?: string): RadioPowerStateEvent | null;
-    /** Requests a physical power transition. Requires `radio:power`. */
-    set(state: RadioPowerTarget, options?: RadioPowerSetOptions): Promise<RadioPowerResponse>;
+}
+/** Declarative power-state transition accepted by `ctx.radioPowerCommands`. */
+export type PluginRadioPowerCommand = {
+    /** Command discriminator. */
+    type: 'set-power';
+    /** Requested physical/controller power target. */
+    state: RadioPowerTarget;
+    /** Optional profile selection and automatic engine startup behavior. */
+    options?: RadioPowerSetOptions;
+};
+/** Capability-scoped physical power command port for `radio:power` plugins. */
+export interface RadioPowerCommandPort {
+    /** Requests a power transition and resolves with the Host's final state. */
+    submit(command: PluginRadioPowerCommand): Promise<RadioPowerResponse>;
 }
 /**
  * Filter criteria for querying QSO records from the logbook.
@@ -333,35 +482,37 @@ export interface QSOQueryFilter {
 /**
  * Callsign-bound view over a single logbook.
  *
- * The host resolves the concrete logbook lazily on each operation, which keeps
- * the handle valid even if the underlying logbook is created or reloaded later.
+ * The host resolves an already registered concrete logbook on each operation,
+ * which keeps the handle valid across reloads without implicitly creating data.
  */
-export interface CallsignLogbookAccess {
+export interface CallsignLogbookReadAccess {
     /** Normalized callsign that scopes this accessor. */
     readonly callsign: string;
-    /** Returns the resolved logbook id, or null when no logbook exists yet. */
+    /** Returns the resolved logbook id, or null when no logbook is registered. */
     getLogBookId(): Promise<string | null>;
     /** Queries QSO records matching the given filter. */
     queryQSOs(filter: QSOQueryFilter): Promise<import('@tx5dr/contracts').QSORecord[]>;
     /** Counts QSO records matching the given filter. */
     countQSOs(filter?: QSOQueryFilter): Promise<number>;
-    /** Adds a new QSO record to this callsign's logbook. */
-    addQSO(record: import('@tx5dr/contracts').QSORecord): Promise<void>;
-    /** Updates partial fields of an existing QSO record. */
-    updateQSO(qsoId: string, updates: Partial<import('@tx5dr/contracts').QSORecord>): Promise<void>;
     /** Returns current statistics for this callsign's logbook. */
     getStatistics(): Promise<import('@tx5dr/contracts').LogBookStatistics | null>;
+}
+/** Durable mutation operations scoped to one normalized station callsign. */
+export interface CallsignLogbookCommandPort {
+    /** Normalized callsign that scopes this accessor. */
+    readonly callsign: string;
+    /** Adds a QSO and resolves with the final record after durable commit. */
+    addQSO(record: import('@tx5dr/contracts').QSORecord): Promise<import('@tx5dr/contracts').QSORecord>;
+    /** Updates a QSO and resolves with the final record after durable commit. */
+    updateQSO(qsoId: string, updates: Partial<import('@tx5dr/contracts').QSORecord>): Promise<import('@tx5dr/contracts').QSORecord>;
     /** Notifies the frontend that this callsign's logbook changed. */
     notifyUpdated(operatorId?: string): Promise<void>;
 }
-/**
- * Full logbook access for plugins.
- *
- * Extends the original read-only helpers with query, write and notification
- * capabilities so that sync providers can self-orchestrate their entire flow
- * without host-side special handling.
- */
-export interface LogbookAccess {
+/** Combined read/write callsign-bound logbook capability. */
+export interface CallsignLogbookAccess extends CallsignLogbookReadAccess, CallsignLogbookCommandPort {
+}
+/** Read-only worked-status and QSO query capability for `logbook:read`. */
+export interface LogbookReadAccess {
     /** Checks whether the callsign has already been worked. */
     hasWorked(callsign: string, options?: {
         anyBand?: boolean;
@@ -374,14 +525,24 @@ export interface LogbookAccess {
     queryQSOs(filter: QSOQueryFilter): Promise<import('@tx5dr/contracts').QSORecord[]>;
     /** Counts QSO records matching the given filter. */
     countQSOs(filter?: QSOQueryFilter): Promise<number>;
-    /** Returns a callsign-bound accessor suitable for global plugin instances. */
-    forCallsign(callsign: string): CallsignLogbookAccess;
-    /** Adds a new QSO record. Deduplication is the caller's responsibility. */
-    addQSO(record: import('@tx5dr/contracts').QSORecord): Promise<void>;
-    /** Updates partial fields of an existing QSO record (e.g. QSL status). */
-    updateQSO(qsoId: string, updates: Partial<import('@tx5dr/contracts').QSORecord>): Promise<void>;
+    /** Returns a read-only callsign-bound accessor suitable for global plugin instances. */
+    forCallsign(callsign: string): CallsignLogbookReadAccess;
+}
+/** Durable mutation operations exposed by the `logbook:write` permission. */
+export interface LogbookCommandPort {
+    /** Adds a QSO and resolves with the final record after durable commit. */
+    addQSO(record: import('@tx5dr/contracts').QSORecord): Promise<import('@tx5dr/contracts').QSORecord>;
+    /** Updates a QSO and resolves with the final record after durable commit. */
+    updateQSO(qsoId: string, updates: Partial<import('@tx5dr/contracts').QSORecord>): Promise<import('@tx5dr/contracts').QSORecord>;
     /** Notifies the frontend to refresh logbook data (call after batch writes). */
     notifyUpdated(): Promise<void>;
+    /** Returns a callsign-bound durable mutation port for global plugin instances. */
+    forCallsign(callsign: string): CallsignLogbookCommandPort;
+}
+/** @deprecated Prefer capability-specific LogbookReadAccess and LogbookCommandPort. */
+export interface LogbookAccess extends LogbookReadAccess, LogbookCommandPort {
+    /** Returns a combined read/write accessor for the requested station callsign. */
+    forCallsign(callsign: string): CallsignLogbookAccess;
 }
 /**
  * Optional constraints used when asking the host for a quieter transmit offset.
@@ -431,7 +592,9 @@ export interface BandAccess {
      * decode environment.
      *
      * Returns `null` when the host cannot evaluate the slot or when no suitable
-     * idle window is found.
+     * idle window is found. A successful result also reserves that offset for the
+     * current operator and analyzed slot so later operators avoid selecting the
+     * same window.
      */
     findIdleTransmitFrequency(options?: IdleTransmitFrequencyOptions): number | null;
     /**
@@ -473,7 +636,8 @@ export interface PanelMeta {
  */
 export interface UIBridge {
     /**
-     * Publishes new panel data for the given declarative panel id.
+     * Publishes a JSON-compatible snapshot for the given declarative panel id.
+     * Mutating the caller's object after this call does not alter panel state.
      */
     send(panelId: string, data: unknown): void;
     /**
@@ -502,7 +666,7 @@ export interface UIBridge {
      */
     registerPageHandler(handler: PluginUIHandler): void;
     /**
-     * Pushes a custom message to the specific page session.
+     * Pushes a JSON-compatible data snapshot to the specific page session.
      *
      * Prefer this API whenever the plugin already knows the target session id
      * (for example from {@link PluginUIRequestContext.pageSessionId} or
@@ -517,7 +681,7 @@ export interface UIBridge {
      */
     listActivePageSessions(pageId: string): PluginUIPageSessionInfo[];
     /**
-     * Pushes a custom message to an iframe UI page by page id.
+     * Pushes a JSON-compatible data snapshot to an iframe UI page by page id.
      *
      * This compatibility helper only succeeds when exactly one active session of
      * the current plugin instance matches the page id. If multiple sessions are
@@ -529,8 +693,9 @@ export interface UIBridge {
  * Handler for custom messages sent from iframe UI pages.
  *
  * Plugins register a handler via `ctx.ui.registerPageHandler()` to receive
- * arbitrary invoke requests from their iframe-based UIs. The host acts as a
- * transparent router — it does not inspect or interpret the action or data.
+ * application-defined invoke requests from their iframe-based UIs. The Host
+ * does not interpret the business schema, but it enforces the page/session
+ * authorization and JSON data boundary in both directions.
  */
 export interface PluginUIHandler {
     /**
@@ -538,49 +703,77 @@ export interface PluginUIHandler {
      *
      * @param pageId - The page that sent the message.
      * @param action - Developer-defined action identifier.
-     * @param data - Arbitrary payload from the iframe.
+     * @param data - JSON-compatible snapshot from the iframe; validate it as
+     *   untrusted input before use.
      * @param requestContext - Host-authenticated page context, including any
      * bound resource for this page session.
-     * @returns The response value sent back to the iframe.
+     * @returns A JSON-compatible response snapshot sent back to the iframe.
      */
     onMessage(pageId: string, action: string, data: unknown, requestContext: PluginUIRequestContext): Promise<unknown>;
 }
+/** Host-authenticated user identity attached to an iframe invoke request. */
 export interface PluginUIRequestUser {
+    /** Stable token/session identifier; not the raw credential. */
     readonly tokenId: string;
+    /** Effective role at the time the Host authorizes the request. */
     readonly role: 'viewer' | 'operator' | 'admin';
+    /** Operator IDs the current user is allowed to access. */
     readonly operatorIds: string[];
+    /** Fine-grained grants associated with the authenticated user, when present. */
     readonly permissionGrants?: PermissionGrant[];
 }
+/** Resource identity resolved and authorized from the page descriptor binding. */
 export interface PluginUIBoundResource {
+    /** Kind declared by `resourceBinding`. */
     readonly kind: 'callsign' | 'operator';
+    /** Normalized callsign or authorized operator ID. */
     readonly value: string;
 }
+/** Plugin instance selected by the Host for this page request. */
 export type PluginUIInstanceTarget = {
     readonly kind: 'global';
 } | {
     readonly kind: 'operator';
     readonly operatorId: string;
 };
+/** Read-only identity of one active plugin iframe page session. */
 export interface PluginUIPageSessionInfo {
+    /** Unique ID used for exact session pushes. */
     readonly sessionId: string;
+    /** `PluginDefinition.ui.pages` entry rendered by this session. */
     readonly pageId: string;
+    /** Host-authorized resource binding, when the page declares one. */
     readonly resource?: PluginUIBoundResource;
 }
+/** Page-session identity plus an exact push channel back to that iframe. */
 export interface PluginUIPageContext extends PluginUIPageSessionInfo {
+    /** Sends a JSON-compatible snapshot to this exact page session. */
     push(action: string, data?: unknown): void;
 }
+/**
+ * Host-authenticated context passed to an iframe page handler.
+ *
+ * Treat `data` from the iframe as untrusted input. Use this context, rather
+ * than caller-supplied IDs, for authorization and storage scoping.
+ */
 export interface PluginUIRequestContext {
+    /** Same exact page session identifier exposed as `page.sessionId`. */
     readonly pageSessionId: string;
+    /** User identity authorized by the Host for this request. */
     readonly user: PluginUIRequestUser;
+    /** Bound callsign/operator, when required by the page descriptor. */
     readonly resource?: PluginUIBoundResource;
+    /** Global or operator plugin instance receiving the request. */
     readonly instanceTarget: PluginUIInstanceTarget;
+    /** Exact page session/push capability, valid only during the current handler invocation. */
     readonly page: PluginUIPageContext;
     /**
      * Page-scoped file storage shared with iframe `tx5dr.file*()` calls.
      *
      * Use this in `registerPageHandler()` handlers to read files uploaded by the
      * current iframe page session without reconstructing host-internal scope
-     * paths.
+     * paths. Both `page` and `files` are exact-invocation capabilities: do not
+     * retain and invoke them after the current `onMessage()` promise settles.
      */
     readonly files: PluginFileStore;
 }
@@ -591,9 +784,9 @@ export interface PluginUIRequestContext {
  * traversal outside the sandbox is rejected by the host.
  */
 export interface PluginFileStore {
-    /** Writes (or overwrites) a file at the given path. */
+    /** Writes a copy of the Buffer, creating or replacing the file. */
     write(path: string, data: Buffer): Promise<void>;
-    /** Reads a file. Returns `null` when the path does not exist. */
+    /** Reads a file into a new Buffer. Returns `null` when the path does not exist. */
     read(path: string): Promise<Buffer | null>;
     /** Deletes a file. Returns `true` if the file existed and was removed. */
     delete(path: string): Promise<boolean>;