@tx5dr/plugin-api 1.7.12 → 2.0.0

package/dist/context.d.ts

@@ -1,4 +1,5 @@
-import type { KVStore, PluginLogger, PluginTimers, OperatorControl, RadioControl, LogbookAccess, BandAccess, UIBridge, PluginFileStore, PluginNetworkControl } from './helpers.js';
+import type { KVStore, PluginLogger, PluginTimers, OperatorSnapshot, OperatorCommandPort, RadioView, RadioCapabilitiesView, RadioCommandPort, RadioTunerCommandPort, RadioPowerView, RadioPowerCommandPort, LogbookReadAccess, LogbookAccess, BandAccess, UIBridge, PluginFileStore, PluginNetworkControl, PluginEventBus } from './helpers.js';
+import type { PluginPermission } from '@tx5dr/contracts';
 import type { LogbookSyncRegistrar } from './sync.js';
 import type { HostSettingsControl } from './settings.js';
 import type { HostDependencies } from './host-dependencies.js';
@@ -15,12 +16,13 @@ import type { HostDependencies } from './host-dependencies.js';
  * here, plugin code should treat it as unavailable rather than reaching into
  * TX-5DR internals.
  */
-export interface PluginContext {
+export interface PluginContextBase {
     /**
      * Resolved plugin configuration values.
      *
-     * The host validates and persists settings, then injects the final values into
-     * this readonly map before invoking hooks or lifecycle methods. Use
+     * The host validates and persists settings, then supplies a detached snapshot
+     * before invoking hooks or lifecycle methods. Mutating nested values does not
+     * update persistence; call {@link PluginContextBase.updateConfig} instead. Use
      * {@link PluginHooks.onConfigChange} to react to updates.
      */
     readonly config: Readonly<Record<string, unknown>>;
@@ -64,24 +66,12 @@ export interface PluginContext {
      * prefer this over raw `setInterval` calls inside plugin code.
      */
     readonly timers: PluginTimers;
+    /** Read-only snapshot and query surface for the current operator. */
+    readonly operator: OperatorSnapshot;
     /**
-     * Control surface for the current operator.
+     * Read-only projection of the physical radio state.
      */
-    readonly operator: OperatorControl;
-    /**
-     * Access to the physical radio state and tuning controls.
-     */
-    readonly radio: RadioControl;
-    /**
-     * Full logbook access — read-only queries, record writes and UI notifications.
-     *
-     * Provides the original read-only helpers (`hasWorked`, `hasWorkedDXCC`,
-     * `hasWorkedGrid`) plus advanced query (`queryQSOs`, `countQSOs`), write
-     * (`addQSO`, `updateQSO`) and notification (`notifyUpdated`) capabilities.
-     * Sync providers and other data-oriented plugins use the write methods to
-     * self-orchestrate their flow without host-side special handling.
-     */
-    readonly logbook: LogbookAccess;
+    readonly radio: RadioView;
     /**
      * Read-only access to current-band and slot decode data.
      */
@@ -99,42 +89,91 @@ export interface PluginContext {
      * For structured JSON data, prefer {@link PluginContext.store} instead.
      */
     readonly files: PluginFileStore;
-    /**
-     * Logbook sync registration entry point.
-     *
-     * Utility plugins that implement logbook synchronization call
-     * `ctx.logbookSync.register(provider)` during `onLoad` to register their
-     * sync provider. The host manages the provider lifecycle and UI integration.
-     */
+}
+type CapabilityProperty<Permissions extends readonly PluginPermission[], Permission extends PluginPermission, Property extends object> = number extends Permissions['length'] ? object : Permission extends Permissions[number] ? Property : object;
+type SettingsCapability<Permissions extends readonly PluginPermission[]> = number extends Permissions['length'] ? object : Extract<Permissions[number], `settings:${string}`> extends never ? object : {
+    readonly settings: CapabilityProperty<Permissions, 'settings:ft8', Pick<HostSettingsControl, 'ft8'>> & CapabilityProperty<Permissions, 'settings:decode-windows', Pick<HostSettingsControl, 'decodeWindows'>> & CapabilityProperty<Permissions, 'settings:realtime', Pick<HostSettingsControl, 'realtime'>> & CapabilityProperty<Permissions, 'settings:frequency-presets', Pick<HostSettingsControl, 'frequencyPresets'>> & CapabilityProperty<Permissions, 'settings:station', Pick<HostSettingsControl, 'station'>> & CapabilityProperty<Permissions, 'settings:psk-reporter', Pick<HostSettingsControl, 'pskReporter'>> & CapabilityProperty<Permissions, 'settings:ntp', Pick<HostSettingsControl, 'ntp'>>;
+};
+type LogbookCapability<Permissions extends readonly PluginPermission[]> = number extends Permissions['length'] ? object : 'logbook:write' extends Permissions[number] ? {
+    readonly logbook: LogbookAccess;
+} : 'logbook:read' extends Permissions[number] ? {
+    readonly logbook: LogbookReadAccess;
+} : object;
+/**
+ * Plugin context whose privileged ports are derived from literal manifest
+ * permissions. Capabilities that were not declared do not exist in the type.
+ *
+ * Host handles are invocation-scoped. In particular, a `Response` returned by
+ * `ctx.fetch` and its Headers/body reader must be consumed before the current
+ * Host callback settles; retaining the native handle for later use results in
+ * `PLUGIN_INVOCATION_EXPIRED`.
+ */
+export type PluginContextFor<Permissions extends readonly PluginPermission[]> = PluginContextBase & CapabilityProperty<Permissions, 'operator:transmit-control', {
+    readonly operatorCommands: OperatorCommandPort;
+}> & CapabilityProperty<Permissions, 'radio:read', {
+    readonly radioCapabilities: RadioCapabilitiesView;
+    readonly radioPower: RadioPowerView;
+}> & CapabilityProperty<Permissions, 'radio:control', {
+    readonly radioCommands: RadioCommandPort;
+}> & CapabilityProperty<Permissions, 'radio:tuner-control', {
+    readonly radioTunerCommands: RadioTunerCommandPort;
+}> & CapabilityProperty<Permissions, 'radio:power', {
+    readonly radioPowerCommands: RadioPowerCommandPort;
+}> & LogbookCapability<Permissions> & CapabilityProperty<Permissions, 'logbook:sync', {
     readonly logbookSync: LogbookSyncRegistrar;
-    /**
-     * Permission-gated host settings control surface.
-     *
-     * Each namespace requires the matching `settings:*` manifest permission.
-     */
-    readonly settings: HostSettingsControl;
-    /**
-     * Permission-gated network capabilities.
-     *
-     * UDP sockets are host-managed and automatically closed when the plugin
-     * instance unloads. This is intentionally protocol-agnostic; protocol codecs
-     * such as WSJT-X UDP belong inside plugins.
-     */
-    readonly network?: PluginNetworkControl;
-    /**
-     * Host-owned runtime dependencies exposed to plugins.
-     *
-     * Native dependencies such as Hamlib are loaded by the host process. Each
-     * dependency is optional and requires its own manifest permission; feature
-     * detect before use.
-     */
-    readonly hostDependencies: HostDependencies;
-    /**
-     * Permission-gated HTTP client.
-     *
-     * This method is only available when the plugin declares the corresponding
-     * network permission. Treat it as optional and feature-detect before calling.
-     */
-    readonly fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+}> & SettingsCapability<Permissions> & CapabilityProperty<Permissions, 'network', {
+    readonly network: PluginNetworkControl;
+    readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}> & CapabilityProperty<Permissions, 'plugin:event-bus', {
+    readonly eventBus: PluginEventBus;
+}> & CapabilityProperty<Permissions, 'host:hamlib', {
+    readonly hostDependencies: HostDependencies & Required<Pick<HostDependencies, 'hamlib'>>;
+}>;
+/** Safe default context for code that has not declared literal permissions. */
+export type PluginContext = PluginContextFor<readonly []>;
+/**
+ * Teardown-only context passed to `onUnload`.
+ *
+ * Cleanup may inspect the read-only operator state, flush plugin-owned state
+ * and release plugin-owned files. The Host also permits previously acquired
+ * native-resource and UI handles to finish cleanup, but does not reopen radio,
+ * network, event-bus, logbook or command capabilities while the instance is
+ * being revoked.
+ */
+export type PluginCleanupContext = Pick<PluginContextBase, 'store' | 'log' | 'timers' | 'files' | 'operator'>;
+/** Host-side erased runtime shape. Public plugin definitions should use `definePlugin()`. */
+export type RuntimePluginContext = PluginContextBase & Partial<{
+    operatorCommands: OperatorCommandPort;
+    radioCapabilities: RadioCapabilitiesView;
+    radioCommands: RadioCommandPort;
+    radioTunerCommands: RadioTunerCommandPort;
+    radioPower: RadioPowerView;
+    radioPowerCommands: RadioPowerCommandPort;
+    logbook: LogbookReadAccess | LogbookAccess;
+    logbookSync: LogbookSyncRegistrar;
+    settings: Partial<HostSettingsControl>;
+    network: PluginNetworkControl;
+    eventBus: PluginEventBus;
+    hostDependencies: HostDependencies;
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}>;
+/**
+ * Deliberately narrow context captured by a speculative strategy runtime.
+ * Decisions can inspect operator state and emit a result, but cannot retain a
+ * command, radio, logbook-write, network, timer or UI capability.
+ */
+export interface StrategyPluginContext {
+    /** Detached snapshot of the strategy plugin's resolved configuration. */
+    readonly config: Readonly<Record<string, unknown>>;
+    /** Logger scoped to this strategy instance. */
+    readonly log: PluginLogger;
+    /** Read-only operator snapshot; mutation ports are deliberately absent. */
+    readonly operator: OperatorSnapshot;
+}
+/** Minimal context used to evaluate a transmit-control eligibility predicate. */
+export interface PluginEligibilityContext {
+    /** Current detached configuration snapshot used by the synchronous gate. */
+    readonly config: Readonly<Record<string, unknown>>;
 }
+export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,oBAAoB,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEnD;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE;QACd;;WAEG;QACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAEzB;;WAEG;QACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC5B,CAAC;IAEF;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAE3C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IAEvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAExC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACzE"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/definition.d.ts

@@ -1,5 +1,5 @@
 import type { PluginSettingDescriptor, PluginQuickAction, PluginQuickSetting, PluginPanelDescriptor, PluginPermission, PluginType, PluginInstanceScope, PluginUIPageDescriptor } from '@tx5dr/contracts';
-import type { PluginContext } from './context.js';
+import type { PluginCleanupContext, PluginContextFor, PluginEligibilityContext, StrategyPluginContext } from './context.js';
 import type { PluginHooks } from './hooks.js';
 import type { StrategyRuntime } from './runtime.js';
 /**
@@ -21,32 +21,43 @@ import type { StrategyRuntime } from './runtime.js';
  *
  * @example
  * ```js
- * /** @type {import('@tx5dr/plugin-api').PluginDefinition} *\/
- * export default {
+ * import { definePlugin } from '@tx5dr/plugin-api';
+ *
+ * export default definePlugin({
+ *   apiVersion: 2,
  *   name: 'my-plugin',
  *   version: '1.0.0',
  *   type: 'utility',
  *   description: 'Annotates interesting decoded stations.',
+ *   permissions: [],
  *   hooks: {
  *     onDecode(messages, ctx) {
  *       ctx.log.info('decoded', { count: messages.length });
  *     },
  *   },
- * };
+ * });
  * ```
  *
  * @example
  * ```ts
- * import type { PluginDefinition } from '@tx5dr/plugin-api';
+ * import { definePlugin } from '@tx5dr/plugin-api';
  *
- * const plugin: PluginDefinition = {
+ * export default definePlugin({
+ *   apiVersion: 2,
  *   name: 'my-strategy',
  *   version: '1.0.0',
  *   type: 'strategy',
- *   createStrategyRuntime(ctx) {
+ *   createStrategyRuntime() {
  *     return {
+ *       checkpoint() {
+ *         return {};
+ *       },
+ *       restore() {},
  *       decide() {
- *         return { stop: false };
+ *         return {
+ *           transmission: null,
+ *           snapshot: this.getSnapshot(),
+ *         };
  *       },
  *       getTransmitText() {
  *         return null;
@@ -61,12 +72,18 @@ import type { StrategyRuntime } from './runtime.js';
  *       reset() {},
  *     };
  *   },
- * };
- *
- * export default plugin;
+ * });
  * ```
  */
-export interface PluginDefinition {
+export interface PluginDefinition<Permissions extends readonly PluginPermission[] = readonly []> {
+    /**
+     * Public API contract version. All new plugins should use `2`.
+     *
+     * API v2 is required for strategy plugins and for utility plugins that request
+     * any mutation capability: `operator:transmit-control`, `radio:control`,
+     * `radio:tuner-control`, `radio:power`, `logbook:write` or `logbook:sync`.
+     */
+    apiVersion?: 2;
     /**
      * Stable machine-readable plugin identifier.
      *
@@ -91,11 +108,19 @@ export interface PluginDefinition {
      *   do not own the core automation state machine.
      */
     type: PluginType;
+    /** Optional strategy capabilities advertised to Host UI and routing. */
+    strategyFeatures?: {
+        /** Declares the `QueuedStrategyRuntime` assisted-target queue contract. */
+        targetQueue?: 1;
+    };
     /**
      * Controls whether the host creates one instance per operator or a single
      * shared instance for the whole station.
      *
      * Defaults to `operator` when omitted.
+     * Global scope is utility-only. It cannot use operator-scoped settings or
+     * quick settings, and only global-compatible hooks/panels are accepted by the
+     * loader. Use it for station-wide sync, network services and radio policy.
      */
     instanceScope?: PluginInstanceScope;
     /**
@@ -111,7 +136,7 @@ export interface PluginDefinition {
      * Permissions allow the host to gate sensitive features such as network
      * access. Always declare the smallest set that the plugin truly needs.
      */
-    permissions?: PluginPermission[];
+    permissions?: Permissions;
     /**
      * Declarative settings schema for generated configuration forms.
      *
@@ -195,15 +220,15 @@ export interface PluginDefinition {
      * should be omitted for utility plugins. The returned runtime becomes the
      * operator's active automation controller.
      */
-    createStrategyRuntime?(ctx: PluginContext): StrategyRuntime;
+    createStrategyRuntime?(ctx: StrategyPluginContext): StrategyRuntime;
     /**
      * Runs after the plugin instance has been loaded and the context is ready.
      *
-     * Use this for startup work such as warming caches, scheduling timers or
-     * sending initial panel data. Keep it fast; long-running work should be
-     * deferred or done asynchronously.
+     * Use this for startup work such as warming caches, scheduling Host timers or
+     * sending initial panel data. Await required asynchronous work before returning;
+     * do not detach continuations that retain Host capabilities after the callback.
      */
-    onLoad?(ctx: PluginContext): void | Promise<void>;
+    onLoad?(ctx: PluginContextFor<Permissions>): void | Promise<void>;
     /**
      * Runs before the plugin instance is unloaded.
      *
@@ -211,13 +236,41 @@ export interface PluginDefinition {
      * handled through the host abstractions. Any timers created via
      * {@link PluginContext.timers} are cleared automatically by the host.
      */
-    onUnload?(ctx: PluginContext): void | Promise<void>;
+    onUnload?(ctx: PluginCleanupContext): void | Promise<void>;
     /**
      * Event and pipeline hooks implemented by the plugin.
      *
      * Hooks let utility plugins observe or transform the message flow, and let the
      * active strategy participate in decision making.
      */
-    hooks?: PluginHooks;
+    hooks?: PluginHooks<Permissions>;
+    /**
+     * Safety gate for the operator command port.
+     *
+     * Plugins that declare `operator:transmit-control` must implement this or
+     * {@link isAutoCallEnabled}. The host evaluates it immediately before each
+     * command so disabled remote-control or integration features cannot retain
+     * command authority.
+     */
+    isTransmitControlEnabled?(ctx: PluginEligibilityContext): boolean;
+    /**
+     * Marks an operator-scoped plugin as an automatic calling controller and
+     * reports whether that behavior is currently enabled.
+     *
+     * The host uses this declaration for the auto-call indicator and pause UI.
+     * It also acts as the command-port safety gate when
+     * {@link isTransmitControlEnabled} is omitted. Integrations that can submit
+     * occasional external commands but are not auto-call controllers should
+     * implement only {@link isTransmitControlEnabled}.
+     */
+    isAutoCallEnabled?(ctx: PluginEligibilityContext): boolean;
 }
+/** Type-erased plugin definition used by the host after module loading. */
+export type AnyPluginDefinition = PluginDefinition<any>;
+/**
+ * Defines a plugin while preserving literal permissions for capability-aware
+ * callback context inference. New plugins should use this helper instead of
+ * widening their definition to `PluginDefinition`.
+ */
+export declare function definePlugin<const Permissions extends readonly PluginPermission[] = readonly []>(definition: PluginDefinition<Permissions>): PluginDefinition<Permissions>;
 //# sourceMappingURL=definition.d.ts.map

package/dist/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IAEpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEjC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAEjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,CAAC,QAAQ,GAAG,UAAU,CAAC,EAAE,CAAA;KAAE,CAAC;IAEhD;;;;;;;;;;;;OAYG;IACH,EAAE,CAAC,EAAE;QACH,yEAAyE;QACzE,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,kCAAkC;QAClC,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;KAClC,CAAC;IAEF;;;;;;OAMG;IACH,qBAAqB,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,CAAC;IAE5D;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"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"}

package/dist/definition.js

@@ -1,2 +1,9 @@
-export {};
+/**
+ * Defines a plugin while preserving literal permissions for capability-aware
+ * callback context inference. New plugins should use this helper instead of
+ * widening their definition to `PluginDefinition`.
+ */
+export function definePlugin(definition) {
+    return definition;
+}
 //# sourceMappingURL=definition.js.map

package/dist/definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":""}
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"AAoTA;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAE1B,UAAyC;IACzC,OAAO,UAAU,CAAC;AACpB,CAAC"}