@dusted/anqst 0.1.3 → 1.0.0

package/dist/src/build-stamp.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ANQST_BUILD_STAMP = void 0;
 // Generated by scripts/build-with-stamp.js. Do not edit by hand.
-exports.ANQST_BUILD_STAMP = "0.1.3/da5d2ee_clean_build_1/2026-03-11";
+exports.ANQST_BUILD_STAMP = "1.0.0/7bd720a_dirty_build_1/2026-03-29";

package/dist/src/emit.js

@@ -12,7 +12,6 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const typescript_1 = __importDefault(require("typescript"));
 const pngjs_1 = require("pngjs");
-const build_stamp_1 = require("./build-stamp");
 const layout_1 = require("./layout");
 function stripAnQstType(typeText) {
     return typeText
@@ -627,6 +626,27 @@ function buildCppTypeContext(spec) {
     }
     return normalizer.buildContext();
 }
+function collectDragDropMimeConstants(spec) {
+    const seen = new Set();
+    const constants = [];
+    for (const service of spec.services) {
+        for (const member of service.members) {
+            if ((member.kind === "DropTarget" || member.kind === "HoverTarget") && member.payloadTypeText) {
+                const typeName = member.payloadTypeText.replace(/\s/g, "");
+                const key = `${service.name}-${typeName}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                constants.push({
+                    typeName,
+                    serviceName: service.name,
+                    mimeType: `application/anqst-dragdropevent_${service.name}-${typeName}`
+                });
+            }
+        }
+    }
+    return constants;
+}
 function renderTypesHeader(spec, cppTypes) {
     const decls = cppTypes.orderedDecls.map(renderCppDecl).join("\n\n");
     const metatypes = cppTypes.structNames
@@ -635,6 +655,11 @@ function renderTypesHeader(spec, cppTypes) {
         `Q_DECLARE_METATYPE(QList<${spec.widgetName}::${name}>)`
     ])
         .join("\n");
+    const mimeConstants = collectDragDropMimeConstants(spec);
+    const mimeConstantLines = mimeConstants
+        .map((c) => `static constexpr const char* kDragDropMime_${c.typeName} = "${c.mimeType}";`)
+        .join("\n");
+    const mimeBlock = mimeConstantLines.length > 0 ? `\n${mimeConstantLines}\n` : "";
     return `#pragma once
 #include <QString>
 #include <QStringList>
@@ -647,7 +672,7 @@ function renderTypesHeader(spec, cppTypes) {
 namespace ${spec.widgetName} {
 
 ${decls}
-
+${mimeBlock}
 } // namespace ${spec.widgetName}
 
 ${metatypes}
@@ -710,6 +735,15 @@ function renderWidgetHeader(spec, cppTypes) {
                     publicSlots.push(`void ${member.name}Slot(const ${cppType}& value);`);
                 }
             }
+            else if (member.kind === "DropTarget" && member.payloadTypeText) {
+                const cppType = cppTypes.mapTypeText(member.payloadTypeText, [service.name, member.name, "Payload"]);
+                signals.push(`void ${member.name}(const ${cppType}& payload, double x, double y);`);
+            }
+            else if (member.kind === "HoverTarget" && member.payloadTypeText) {
+                const cppType = cppTypes.mapTypeText(member.payloadTypeText, [service.name, member.name, "Payload"]);
+                signals.push(`void ${member.name}(const ${cppType}& payload, double x, double y);`);
+                signals.push(`void ${member.name}Left();`);
+            }
         }
     }
     return `#pragma once
@@ -860,6 +894,45 @@ function renderCppStub(spec, cppTypes) {
     lines.push(`    Q_UNUSED(kResourcesInitialized);`);
     lines.push(`    registerGeneratedMetaTypes();`);
     lines.push(`    installBridgeBindings();`);
+    for (const service of spec.services) {
+        for (const member of service.members) {
+            if (member.kind === "DropTarget" && member.payloadTypeText) {
+                const typeName = member.payloadTypeText.replace(/\s/g, "");
+                const mimeConst = `${spec.widgetName}::kDragDropMime_${typeName}`;
+                lines.push(`    registerDropTarget(QStringLiteral("${service.name}"), QStringLiteral("${member.name}"), QString::fromUtf8(${mimeConst}));`);
+            }
+            else if (member.kind === "HoverTarget" && member.payloadTypeText) {
+                const typeName = member.payloadTypeText.replace(/\s/g, "");
+                const mimeConst = `${spec.widgetName}::kDragDropMime_${typeName}`;
+                lines.push(`    registerHoverTarget(QStringLiteral("${service.name}"), QStringLiteral("${member.name}"), QString::fromUtf8(${mimeConst}), ${member.hoverThrottleMs});`);
+            }
+        }
+    }
+    for (const service of spec.services) {
+        for (const member of service.members) {
+            if (member.kind === "DropTarget" && member.payloadTypeText) {
+                const cppType = cppTypes.mapTypeText(member.payloadTypeText, [service.name, member.name, "Payload"]);
+                lines.push(`    QObject::connect(this, &AnQstWebHostBase::anQstBridge_dropReceived, this, [this](const QString& service, const QString& member, const QVariant& payload, double x, double y) {`);
+                lines.push(`        if (service == QStringLiteral("${service.name}") && member == QStringLiteral("${member.name}")) {`);
+                lines.push(`            emit ${member.name}(payload.value<${cppType}>(), x, y);`);
+                lines.push(`        }`);
+                lines.push(`    });`);
+            }
+            else if (member.kind === "HoverTarget" && member.payloadTypeText) {
+                const cppType = cppTypes.mapTypeText(member.payloadTypeText, [service.name, member.name, "Payload"]);
+                lines.push(`    QObject::connect(this, &AnQstWebHostBase::anQstBridge_hoverUpdated, this, [this](const QString& service, const QString& member, const QVariant& payload, double x, double y) {`);
+                lines.push(`        if (service == QStringLiteral("${service.name}") && member == QStringLiteral("${member.name}")) {`);
+                lines.push(`            emit ${member.name}(payload.value<${cppType}>(), x, y);`);
+                lines.push(`        }`);
+                lines.push(`    });`);
+                lines.push(`    QObject::connect(this, &AnQstWebHostBase::anQstBridge_hoverLeft, this, [this](const QString& service, const QString& member) {`);
+                lines.push(`        if (service == QStringLiteral("${service.name}") && member == QStringLiteral("${member.name}")) {`);
+                lines.push(`            emit ${member.name}Left();`);
+                lines.push(`        }`);
+                lines.push(`    });`);
+            }
+        }
+    }
     lines.push(`    QObject::connect(this, &AnQstWebHostBase::onHostError, this, &${widgetClassName}::diagnosticsForwarded);`);
     lines.push(`    const bool rootOk = setContentRoot(QString::fromUtf8(kBootstrapContentRoot));`);
     lines.push(`    const bool bridgeOk = setBridgeObject(this, QString::fromUtf8(kBootstrapBridgeObject));`);
@@ -1007,13 +1080,7 @@ function renderCppStub(spec, cppTypes) {
             lines.push(`    }`);
         }
     }
-    lines.push(`    return QVariantMap{`);
-    lines.push(`        {QStringLiteral("code"), QStringLiteral("HandlerNotRegisteredError")},`);
-    lines.push(`        {QStringLiteral("message"), QStringLiteral("No Call mapping found.")},`);
-    lines.push(`        {QStringLiteral("service"), service},`);
-    lines.push(`        {QStringLiteral("member"), member},`);
-    lines.push(`        {QStringLiteral("requestId"), QString()}`);
-    lines.push(`    };`);
+    lines.push(`    return QVariant();`);
     lines.push(`}`);
     lines.push("");
     lines.push(`void ${widgetClassName}::handleGeneratedEmitter(const QString& service, const QString& member, const QVariantList& args) {`);
@@ -1172,7 +1239,24 @@ function normalizeSlashes(value) {
     return value.split(node_path_1.default.sep).join("/");
 }
 function resolveActiveBuildStamp() {
-    return build_stamp_1.ANQST_BUILD_STAMP.trim();
+    const fromEnv = process.env.ANQST_BUILD_STAMP?.trim();
+    if (fromEnv && fromEnv.length > 0) {
+        return fromEnv;
+    }
+    const activePath = node_path_1.default.resolve(__dirname, "..", "..", ".anqstgen-version-active.json");
+    if (!node_fs_1.default.existsSync(activePath)) {
+        return "";
+    }
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(activePath, "utf8"));
+        if (typeof parsed.active === "string" && parsed.active.trim().length > 0) {
+            return parsed.active.trim();
+        }
+    }
+    catch {
+        return "";
+    }
+    return "";
 }
 function withBuildStamp(relativePath, content) {
     const stamp = resolveActiveBuildStamp();
@@ -1315,6 +1399,19 @@ function renderTsService(spec, serviceName) {
                 constructorBodyLines.push(`    this._bridge.onOutput("${serviceName}", "${m.name}", (value) => this._${m.name}.set(value as ${tsType}));`);
             }
         }
+        if (m.kind === "DropTarget" && m.payloadTypeText) {
+            const tsType = mapTypeTextToTs(m.payloadTypeText);
+            fieldLines.push(`  private readonly _${m.name} = signal<{ payload: ${tsType}; x: number; y: number } | null>(null);`);
+            methodLines.push(`  ${m.name}(): { payload: ${tsType}; x: number; y: number } | null { return this._${m.name}(); }`);
+            constructorBodyLines.push(`    this._bridge.onDrop("${serviceName}", "${m.name}", (payload, x, y) => this._${m.name}.set({ payload: payload as ${tsType}, x, y }));`);
+        }
+        if (m.kind === "HoverTarget" && m.payloadTypeText) {
+            const tsType = mapTypeTextToTs(m.payloadTypeText);
+            fieldLines.push(`  private readonly _${m.name} = signal<{ payload: ${tsType}; x: number; y: number } | null>(null);`);
+            methodLines.push(`  ${m.name}(): { payload: ${tsType}; x: number; y: number } | null { return this._${m.name}(); }`);
+            constructorBodyLines.push(`    this._bridge.onHover("${serviceName}", "${m.name}", (payload, x, y) => this._${m.name}.set({ payload: payload as ${tsType}, x, y }));`);
+            constructorBodyLines.push(`    this._bridge.onHoverLeft("${serviceName}", "${m.name}", () => this._${m.name}.set(null));`);
+        }
     }
     const constructorLines = [
         "  constructor() {",
@@ -1366,6 +1463,14 @@ function renderTsServiceDts(spec, serviceName) {
                 setMembers.push(`  ${m.name}(value: ${tsType}): void;`);
             }
         }
+        if (m.kind === "DropTarget" && m.payloadTypeText) {
+            const tsType = mapTypeTextToTs(m.payloadTypeText);
+            classMembers.push(`  ${m.name}(): { payload: ${tsType}; x: number; y: number } | null;`);
+        }
+        if (m.kind === "HoverTarget" && m.payloadTypeText) {
+            const tsType = mapTypeTextToTs(m.payloadTypeText);
+            classMembers.push(`  ${m.name}(): { payload: ${tsType}; x: number; y: number } | null;`);
+        }
     }
     const setInterfaceDecl = setMembers.length > 0
         ? `export interface ${setInterfaceName} {\n${setMembers.join("\n")}\n}`
@@ -1396,6 +1501,9 @@ type SlotHandler = (...args: unknown[]) => unknown;
 type OutputHandler = (value: unknown) => void;
 type SlotInvocationListener = (requestId: string, service: string, member: string, args: unknown[]) => void;
 type OutputListener = (service: string, member: string, value: unknown) => void;
+type DropListener = (service: string, member: string, payload: unknown, x: number, y: number) => void;
+type HoverListener = (service: string, member: string, payload: unknown, x: number, y: number) => void;
+type HoverLeftListener = (service: string, member: string) => void;
 
 interface HostBridgeApi {
   anQstBridge_call(service: string, member: string, args: unknown[], callback: (result: unknown) => void): void;
@@ -1407,6 +1515,9 @@ interface HostBridgeApi {
   anQstBridge_slotInvocationRequested: {
     connect: (cb: (requestId: string, service: string, member: string, args: unknown[]) => void) => void;
   };
+  anQstBridge_dropReceived: { connect: (cb: (service: string, member: string, payload: unknown, x: number, y: number) => void) => void };
+  anQstBridge_hoverUpdated: { connect: (cb: (service: string, member: string, payload: unknown, x: number, y: number) => void) => void };
+  anQstBridge_hoverLeft: { connect: (cb: (service: string, member: string) => void) => void };
 }
 
 interface QWebChannelCtor {
@@ -1424,6 +1535,9 @@ interface BridgeAdapter {
   resolveSlot(requestId: string, ok: boolean, payload: unknown, error: string): void;
   onOutput(handler: OutputListener): void;
   onSlotInvocation(handler: SlotInvocationListener): void;
+  onDrop(handler: DropListener): void;
+  onHover(handler: HoverListener): void;
+  onHoverLeft(handler: HoverLeftListener): void;
 }
 
 function isBridgeCallError(value: unknown): value is {
@@ -1511,6 +1625,18 @@ class QtWebChannelAdapter implements BridgeAdapter {
   onSlotInvocation(handler: SlotInvocationListener): void {
     this.host.anQstBridge_slotInvocationRequested.connect(handler);
   }
+
+  onDrop(handler: DropListener): void {
+    this.host.anQstBridge_dropReceived.connect(handler);
+  }
+
+  onHover(handler: HoverListener): void {
+    this.host.anQstBridge_hoverUpdated.connect(handler);
+  }
+
+  onHoverLeft(handler: HoverLeftListener): void {
+    this.host.anQstBridge_hoverLeft.connect(handler);
+  }
 }
 
 class WebSocketBridgeAdapter implements BridgeAdapter {
@@ -1523,6 +1649,9 @@ class WebSocketBridgeAdapter implements BridgeAdapter {
   }>();
   private readonly outputListeners: OutputListener[] = [];
   private readonly slotListeners: SlotInvocationListener[] = [];
+  private readonly dropListeners: DropListener[] = [];
+  private readonly hoverListeners: HoverListener[] = [];
+  private readonly hoverLeftListeners: HoverLeftListener[] = [];
   private requestCounter = 0;
 
   private constructor(private readonly socket: WebSocket) {
@@ -1562,6 +1691,34 @@ class WebSocketBridgeAdapter implements BridgeAdapter {
         }
         return;
       }
+      if (type === "dropReceived") {
+        const service = String(message["service"] ?? "");
+        const member = String(message["member"] ?? "");
+        const x = Number(message["x"] ?? 0);
+        const y = Number(message["y"] ?? 0);
+        for (const listener of this.dropListeners) {
+          listener(service, member, message["payload"], x, y);
+        }
+        return;
+      }
+      if (type === "hoverUpdated") {
+        const service = String(message["service"] ?? "");
+        const member = String(message["member"] ?? "");
+        const x = Number(message["x"] ?? 0);
+        const y = Number(message["y"] ?? 0);
+        for (const listener of this.hoverListeners) {
+          listener(service, member, message["payload"], x, y);
+        }
+        return;
+      }
+      if (type === "hoverLeft") {
+        const service = String(message["service"] ?? "");
+        const member = String(message["member"] ?? "");
+        for (const listener of this.hoverLeftListeners) {
+          listener(service, member);
+        }
+        return;
+      }
       if (type === "hostError") {
         console.error("AnQst host error:", message["payload"]);
         return;
@@ -1649,6 +1806,18 @@ class WebSocketBridgeAdapter implements BridgeAdapter {
   onSlotInvocation(handler: SlotInvocationListener): void {
     this.slotListeners.push(handler);
   }
+
+  onDrop(handler: DropListener): void {
+    this.dropListeners.push(handler);
+  }
+
+  onHover(handler: HoverListener): void {
+    this.hoverListeners.push(handler);
+  }
+
+  onHoverLeft(handler: HoverLeftListener): void {
+    this.hoverLeftListeners.push(handler);
+  }
 }
 
 @Injectable({ providedIn: "root" })
@@ -1656,6 +1825,9 @@ class AnQstBridgeRuntime {
   private adapter: BridgeAdapter | null = null;
   private readonly slotHandlers = new Map<string, SlotHandler>();
   private readonly outputHandlers = new Map<string, OutputHandler[]>();
+  private readonly dropHandlers = new Map<string, ((payload: unknown, x: number, y: number) => void)[]>();
+  private readonly hoverHandlers = new Map<string, ((payload: unknown, x: number, y: number) => void)[]>();
+  private readonly hoverLeftHandlers = new Map<string, (() => void)[]>();
   private readonly startup = this.init();
 
   async ready(): Promise<void> {
@@ -1706,6 +1878,27 @@ class AnQstBridgeRuntime {
     this.outputHandlers.set(key, existing);
   }
 
+  onDrop(service: string, member: string, handler: (payload: unknown, x: number, y: number) => void): void {
+    const key = this.key(service, member);
+    const existing = this.dropHandlers.get(key) ?? [];
+    existing.push(handler);
+    this.dropHandlers.set(key, existing);
+  }
+
+  onHover(service: string, member: string, handler: (payload: unknown, x: number, y: number) => void): void {
+    const key = this.key(service, member);
+    const existing = this.hoverHandlers.get(key) ?? [];
+    existing.push(handler);
+    this.hoverHandlers.set(key, existing);
+  }
+
+  onHoverLeft(service: string, member: string, handler: () => void): void {
+    const key = this.key(service, member);
+    const existing = this.hoverLeftHandlers.get(key) ?? [];
+    existing.push(handler);
+    this.hoverLeftHandlers.set(key, existing);
+  }
+
   private requireAdapterSync(): BridgeAdapter {
     if (this.adapter === null) {
       throw new Error("AnQst bridge is not ready.");
@@ -1751,6 +1944,24 @@ class AnQstBridgeRuntime {
         this.adapter!.resolveSlot(requestId, false, undefined, message);
       }
     });
+    this.adapter.onDrop((service, member, payload, x, y) => {
+      const key = this.key(service, member);
+      for (const handler of this.dropHandlers.get(key) ?? []) {
+        handler(payload, x, y);
+      }
+    });
+    this.adapter.onHover((service, member, payload, x, y) => {
+      const key = this.key(service, member);
+      for (const handler of this.hoverHandlers.get(key) ?? []) {
+        handler(payload, x, y);
+      }
+    });
+    this.adapter.onHoverLeft((service, member) => {
+      const key = this.key(service, member);
+      for (const handler of this.hoverLeftHandlers.get(key) ?? []) {
+        handler();
+      }
+    });
     for (const key of this.slotHandlers.keys()) {
       const parts = key.split("::");
       if (parts.length === 2) {
@@ -2790,6 +3001,7 @@ set(CMAKE_AUTOUIC ON)
 set(CMAKE_AUTORCC ON)
 
 find_program(ANQST_NPM_EXECUTABLE npm REQUIRED)
+find_program(ANQST_NPX_EXECUTABLE npx REQUIRED)
 
 add_custom_command(
     OUTPUT
@@ -2801,7 +3013,7 @@ add_custom_command(
         "\${${generatedIncludeVar}}/${widgetName}Types.h"
         "\${${generatedRootVar}}/webapp/index.html"
     COMMAND "\${ANQST_NPM_EXECUTABLE}" install
-    COMMAND "\${ANQST_NPM_EXECUTABLE}" run anqst:build
+    COMMAND "\${ANQST_NPX_EXECUTABLE}" anqst build
     WORKING_DIRECTORY "\${${projectRootVar}}"
     COMMENT "Generating AnQst widget library (${widgetTarget}) from Angular project"
     VERBATIM
@@ -3029,7 +3241,7 @@ function renderQtDesignerPluginCpp(widgetName, widgetCategory, hasIcon) {
 #include <QObject>
 #include <QString>
 #include <QWidget>
-#include "include/${widgetName}.h"
+#include "${widgetName}.h"
 
 class ${pluginClass} final : public QObject, public QDesignerCustomWidgetInterface {
     Q_OBJECT
@@ -3045,9 +3257,10 @@ public:
     QString toolTip() const override { return QStringLiteral("${widgetName} generated by AnQst."); }
     QString whatsThis() const override { return QStringLiteral("${widgetName} generated by AnQst."); }
     bool isContainer() const override { return false; }
-    QString includeFile() const override { return QStringLiteral("include/${widgetName}.h"); }
+    QString includeFile() const override { return QStringLiteral("${widgetName}.h"); }
     QWidget* createWidget(QWidget* parent) override {
         auto* widget = new ${widgetClass}(parent);
+        widget->setMinimumHeight(128);
         widget->setProperty("anqstDesignerContext", true);
         return widget;
     }
@@ -3058,6 +3271,12 @@ public:
         return QStringLiteral(
             "<ui language=\\"c++\\">\\n"
             "  <widget class=\\"${widgetClass}\\" name=\\"${widgetName.toLowerCase()}\\">\\n"
+            "    <property name=\\"minimumSize\\">\\n"
+            "      <size>\\n"
+            "        <width>256</width>\\n"
+            "        <height>128</height>\\n"
+            "      </size>\\n"
+            "    </property>\\n"
             "  </widget>\\n"
             "</ui>\\n");
     }

package/dist/src/parser.js

@@ -55,7 +55,7 @@ function parseMemberKindFromAnQstType(typeNode) {
     if (!typeName.startsWith("AnQst."))
         return null;
     const kind = typeName.slice("AnQst.".length);
-    if (!["Call", "Slot", "Emitter", "Output", "Input"].includes(kind))
+    if (!["Call", "Slot", "Emitter", "Output", "Input", "DropTarget", "HoverTarget"].includes(kind))
         return null;
     if (kind === "Emitter")
         return { kind, payload: null };
@@ -71,7 +71,7 @@ function parseMemberKindWithConfig(typeNode) {
     if (!typeName.startsWith("AnQst."))
         return null;
     const kind = typeName.slice("AnQst.".length);
-    if (!["Call", "Slot", "Emitter", "Output", "Input"].includes(kind))
+    if (!["Call", "Slot", "Emitter", "Output", "Input", "DropTarget", "HoverTarget"].includes(kind))
         return null;
     const typeArgs = typeNode.typeArguments ?? [];
     if (kind === "Emitter") {
@@ -84,7 +84,7 @@ function parseMemberKindWithConfig(typeNode) {
     return {
         kind,
         payload: typeArgs[0] ? typeArgs[0].getText() : null,
-        configTypeNode: kind === "Call" ? (typeArgs[1] ?? null) : null
+        configTypeNode: (kind === "Call" || kind === "HoverTarget") ? (typeArgs[1] ?? null) : null
     };
 }
 function parseNumericLiteralType(node) {
@@ -156,6 +156,51 @@ function resolveMemberTimeoutMs(source, serviceName, memberName, kind, configTyp
     }
     return effectiveMs;
 }
+const DEFAULT_HOVER_RATE_HZ = 60;
+const DEFAULT_HOVER_THROTTLE_MS = Math.round(1000 / DEFAULT_HOVER_RATE_HZ);
+function resolveHoverThrottleMs(source, serviceName, memberName, kind, configTypeNode, warnings, memberLoc) {
+    if (kind !== "HoverTarget")
+        return 0;
+    if (!configTypeNode)
+        return DEFAULT_HOVER_THROTTLE_MS;
+    if (!typescript_1.default.isTypeLiteralNode(configTypeNode)) {
+        throw new errors_1.VerifyError(`HoverTarget config for '${memberName}' must be an inline object literal type.`, locFromNode(source, configTypeNode));
+    }
+    let maxRateHz = null;
+    const memberPath = `${serviceName}.${memberName}`;
+    for (const prop of configTypeNode.members) {
+        if (!typescript_1.default.isPropertySignature(prop) || !prop.name) {
+            throw new errors_1.VerifyError(`HoverTarget config for '${memberName}' only supports named properties.`, locFromNode(source, prop));
+        }
+        if (!typescript_1.default.isIdentifier(prop.name)) {
+            throw new errors_1.VerifyError(`HoverTarget config for '${memberName}' only supports identifier keys.`, locFromNode(source, prop.name));
+        }
+        const key = prop.name.text;
+        if (!prop.type) {
+            throw new errors_1.VerifyError(`HoverTarget config key '${key}' in '${memberName}' must declare a numeric literal value.`, locFromNode(source, prop));
+        }
+        if (key !== "maxRateHz") {
+            warnings.push({
+                severity: "warn",
+                message: `Unknown HoverTarget config key '${key}' ignored for '${memberPath}'.`,
+                loc: locFromNode(source, prop.name),
+                memberPath
+            });
+            continue;
+        }
+        const numericValue = parseNumericLiteralType(prop.type);
+        if (numericValue === null || !Number.isFinite(numericValue)) {
+            throw new errors_1.VerifyError(`HoverTarget config key '${key}' in '${memberName}' must be a numeric literal >= 0.`, locFromNode(source, prop.type));
+        }
+        if (numericValue < 0) {
+            throw new errors_1.VerifyError(`HoverTarget config key '${key}' in '${memberName}' must be >= 0.`, locFromNode(source, prop.type));
+        }
+        maxRateHz = numericValue;
+    }
+    if (maxRateHz === null)
+        return DEFAULT_HOVER_THROTTLE_MS;
+    return maxRateHz === 0 ? 0 : Math.round(1000 / maxRateHz);
+}
 function parseServiceMember(source, serviceName, member, warnings) {
     if (typescript_1.default.isMethodSignature(member)) {
         if (member.questionToken)
@@ -166,7 +211,7 @@ function parseServiceMember(source, serviceName, member, warnings) {
         const parsed = parseMemberKindWithConfig(returnType);
         if (!parsed)
             throw new errors_1.VerifyError(`Unsupported service method return type '${returnType.getText()}'.`, locFromNode(source, member));
-        if (parsed.kind === "Input" || parsed.kind === "Output") {
+        if (parsed.kind === "Input" || parsed.kind === "Output" || parsed.kind === "DropTarget" || parsed.kind === "HoverTarget") {
             throw new errors_1.VerifyError(`${parsed.kind} must be declared as property, not method.`, locFromNode(source, member));
         }
         if (parsed.kind === "Emitter" && parsed.configTypeNode !== null) {
@@ -191,6 +236,7 @@ function parseServiceMember(source, serviceName, member, warnings) {
             payloadTypeText: parsed.payload,
             parameters,
             timeoutMs,
+            hoverThrottleMs: 0,
             loc: locFromNode(source, member)
         };
     }
@@ -202,19 +248,21 @@ function parseServiceMember(source, serviceName, member, warnings) {
         const parsed = parseMemberKindWithConfig(member.type);
         if (!parsed)
             throw new errors_1.VerifyError(`Unsupported service property type '${member.type.getText()}'.`, locFromNode(source, member));
-        if (parsed.kind !== "Input" && parsed.kind !== "Output") {
+        if (parsed.kind !== "Input" && parsed.kind !== "Output" && parsed.kind !== "DropTarget" && parsed.kind !== "HoverTarget") {
             throw new errors_1.VerifyError(`${parsed.kind} must be declared as method, not property.`, locFromNode(source, member));
         }
         if (!member.name || !typescript_1.default.isIdentifier(member.name)) {
             throw new errors_1.VerifyError("Only identifier service property names are supported.", locFromNode(source, member));
         }
         const timeoutMs = resolveMemberTimeoutMs(source, serviceName, member.name.text, parsed.kind, parsed.configTypeNode, warnings, locFromNode(source, member));
+        const hoverThrottleMs = resolveHoverThrottleMs(source, serviceName, member.name.text, parsed.kind, parsed.configTypeNode, warnings, locFromNode(source, member));
         return {
             kind: parsed.kind,
             name: member.name.text,
             payloadTypeText: parsed.payload,
             parameters: [],
             timeoutMs,
+            hoverThrottleMs,
             loc: locFromNode(source, member)
         };
     }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dusted/anqst",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "Opinionated backend generator for webapps.",
   "keywords": [
     "nodejs",
     "qt",
     "angular",
-    "webapp"
+    "webapp",
+    "apigenerator"
   ],
   "homepage": "https://github.com/DusteDdk/AnQst#readme",
   "bugs": {

package/spec/AnQst-Spec-DSL.d.ts

@@ -1,249 +1,327 @@
-/**
- * AnQst-Spec Language - Canonical source of truth for the language.
- *
- * @remarks
- * - DSL for Widget generation, transported as TypeScript definition.
- * - For AnQSt Widget Specifications only.
- * - Exactly one toplevel namespace must be declared: It names the Widget.
- * - Service interfaces are optional. Namespace-local type declarations are valid generation roots.
- * - Imported/external types are generation-relevant when transitively reachable from namespace declarations.
- * - This is not an input file to the generator, it is the description of the language that describes the widget.
- *   Not for use by TypeScript application implementation.
- * @example
- * package.json:
- * - "AnQst": "./AnQst/MyUserMgmtWidget.settings.json"
- */
-
-export namespace AnQst {
-
-    /**
-     * Declare service `InterfaceName`
-     *
-     * @remarks
-     * Multiple allowed.
-     * Affords developers of advanced widgets the ability to create domain-informed categories.
-     * - Duplicate method declarations with identical parameter lists are invalid in normative AnQst-Spec input.
-     *
-     * @example
-     * export interface UserService extends Widget.Service { }
-     * // Generates UserService.
-     */
-    interface Service { }
-
-    /**
-     * Declare service `InterfaceName` as development-mode capable transport service.
-     *
-     * @remarks
-     * - Extends the same method/property semantics as `AnQst.Service`.
-     * - Signals to the generator/runtime that this widget should emit dual-transport bridge support
-     *   (Qt WebChannel + HTTP/WebSocket development bridge).
-     * - Existing generated service APIs remain unchanged.
-     *
-     * @example
-     * export interface UserService extends AnQst.AngularHTTPBaseServerClass { }
-     */
-    interface AngularHTTPBaseServerClass extends Service { }
-
-    type CallConfig = { timeoutSeconds: number } | { timeoutMilliseconds: number } | {};
-
-    /**
-     * Declare non-blocking service method `MethodName`(`MethodArguments`): Promise<`MethodReturnType`>.
-     * @remarks
-     * - **Widget** -> Parent
-     * - Flow:
-     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
-     *   - Widget: Returns Promise<`MethodReturnType`>.
-     *   - Parent: Registered callback receives args and returns `T` synchronously.
-     *   - Widget: Promise resolves with payload `T` or rejects with plain error object.
-     * - Optional config supports timeout tuning:
-     *   - `AnQst.Call<T, { timeoutSeconds: N }>`
-     *   - `AnQst.Call<T, { timeoutMilliseconds: N }>`
-     * - Exactly one timeout key is allowed. Value must be integer >= 0.
-     * - Default timeout is 120s. `0` means wait forever.
-     * @example
-     * // AnQst spec:
-     * getUserById(userId: string): AnQst.Call<User>
-     * //Angular app:
-     * const user: User = await this.userService.getUserById("abc");
-    */
-    interface Call<T, Config extends CallConfig = {}> { dummy: T; config?: Config }
-
-    /**
-     * Declare blocking service method onSlot.`MethodName`( handler(`MethodArguments`):`MethodReturnType` ): void
-     * @remarks
-     * - **Parent** -> Widget
-     * - Impl note: Autogenerated stub handler queues until handler is set (set method calls spools queue through handler)
-     * - Flow:
-     *   - Parent: Call to generated widget method `MethodName`(`MethodArguments`).
-     *   - Widget: Registered handler(`MethodArguments`) is called.
-     *   - Widget: Handler return forms:
-     *      - `T` -> success payload
-     *      - `Promise<T>` -> awaited, success payload on resolve
-     *      - `Error` -> failure
-     *      - throw -> failure
-     *      - rejected promise -> failure
-     *   - Parent: `MethodName` call returns with result.
-     * - Generated C++ Slot methods do not expose `ok/error` out parameters.
-     * - Default Slot timeout is 1000ms.
-     * Note: One active handler, calling will replace existing and is valid and allowed.
-     * @example
-     * // AnQst spec:
-     * getUsernameSubstring(from: number, to:number ): AnQst.Slot<string>
-     * //Angular app:
-     * this.userService.onSlot.getUsername( provider );
-     * //Parent:
-     * auto currentFormUsername = userMgmt.getUsername();
-    */
-    interface Slot<T> { dummy: T }
-
-
-
-    /**
-     * Declare message emission method `MethodName`(`MethodArguments`): void
-     * @remarks
-     * - **Widget** -> ?Parent
-     * True Qt signal semantics (Message is emitted, no return path, no registration requirement)
-     * - Flow:
-     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
-     *   - Widget: Returns void.
-     *   - Parent: Might have something connected to the signal, might not.
-     * - If no listener is connected, event is dropped.
-     * @example
-     * // AnQst spec:
-     * complain(whine: string): AnQst.Emitter;
-     * //Angular app:
-     * this.userService.complain("Why won't you LISTEN!");
-    */
-    interface Emitter { }
-
-
-    /**
-     * Declare reactive `PropertyName`:`OutputType` and set.`PropertyName`(arg: `OutputType`)
-     * @remarks
-     * - **Parent** -> Widget
-     * True Angular signal semantics (Property updates, signal emits, no return path, no registration requirement)
-     * - Flow:
-     *   - Parent: Sets generated widget property `PropertyName`.
-     *   - Widget: Service updates readonly property `PropertyName` and emits signal.
-     * @example
-     * // AnQst spec:
-     * activeUsers: AnQst.Output<number>;
-     * //Angular app template:
-     * <p>{{ userService.activeUsers() }}</p>
-     * //Parent:
-     * int users = userMgmt.activeUsers;
-     * userMgmt.activeUsers = 99;
-     */
-    interface Output<OutputType> {}
-
-
-    /**
-     * Declare Input bindable set.`PropertyName`(input:`InputType`): void and `PropertyName`:`InputType`
-     * @remarks
-     * - **Widget** -> Parent
-     * - Convenience method, for symmetry with Output.
-     * - Flow:
-     *   - Widget: Calls service set.`PropertyName`(`InputType`) to publish current value.
-     *   - Parent: Mirrored generated widget property `PropertyName` is updated and emits change notification.
-     * @example
-     * // AnQst spec:
-     * currentUsername: AnQst.Input<string>;
-     * //Angular app template:
-     * <input type="text" placeholder="Your Name Here" (input)="userService.set.currentUsername(($event.target as HTMLInputElement).value)" />
-     * //Parent:
-     * QString userName = userMgmt.currentUsername;
-     */
-    interface Input<InputType> {}
-
-    /**
-     * AnQst-Spec type mapping overview and control.
-     *
-     * @remarks
-     * Any Type that be mapped between TypeScript and Qt, C++ standard types or
-     *     Plain Old Data (POD) types (in that order of preference) will be mapped by default.
-     *
-     * Canonical mapping directive namespace is AnQst.Type.<type>.
-     * To express advisory mapping preference, use AnQst.Type.<type>.
-     * Advisory means generator SHOULD honor it, but MAY fall back to inferred/default mapping and emit diagnostic.
-     * Array forms are equivalent: T[] == Array<T>, and AnQst.Type.X[] == Array<AnQst.Type.X>.
-     *
-     * TypeScript definitions+classes and C++ structs are generated for each
-     *     structured TypeScript type ( type = {...} or interface { ... } )
-     *     referenced in an AnQst spec.
-     *
-     */
-    enum Type {
-        object = "JavaScript Object <-> QVariantMap (JSON.stringify/parse semantics)",
-        json  = "JavaScript Object <-> QJsonObject (JSON.stringify/parse semantics)",
-        string = "JavaScript String <-> QString",
-        stringArray = "JavaScript String[] <-> QStringList",
-        number = "JavaScript Number <-> double",
-        qint64 = "JavaScript BigInt <-> qint64 (Default, for symmetry, same as direct use of <BigInt> which is allowed.)",
-        quint64 = "JavaScript BigInt <-> quint64",
-        qint32 = "JavaScript Number <-> qint32",
-        quint32 = "JavaScript Number <-> quint32",
-        qint16 = "JavaScript Number <-> qint16",
-        quint16 = "JavaScript Number <-> quint16",
-        qint8 = "JavaScript Number <-> qint8",
-        quint8 = "JavaScript Number <-> quint8",
-        int32 = "JavaScript Number <-> int32_t",
-        uint32 = "JavaScript Number <-> uint32_t",
-        int16 = "JavaScript Number <-> int16_t",
-        uint16 = "JavaScript Number <-> uint16_t",
-        int8 = "JavaScript Number <-> int8_t",
-        uint8 = "JavaScript Number <-> uint8_t",
-        buffer = "JavaScript ArrayBuffer <-> QByteArray (Default, for symmetry, same as direct use of <ArrayBuffer> which is allowed.)",
-        blob = "JavaScript ArrayBuffer <-> QByteArray",
-        typedArray = "JavaScript TypedArray <-> QByteArray",
-        uint8Array = "JavaScript Uint8Array <-> QByteArray",
-        int8Array = "JavaScript Int8Array <-> QByteArray",
-        uint16Array = "JavaScript Uint16Array <-> QByteArray",
-        int16Array = "JavaScript Int16Array <-> QByteArray",
-        uint32Array = "JavaScript Uint32Array <-> QByteArray",
-        int32Array = "JavaScript Int32Array <-> QByteArray",
-        float32Array = "JavaScript Float32Array <-> QByteArray",
-        float64Array = "JavaScript Float64Array <-> QByteArray",
-    }
-
-
-    /**
-     * These are explicitly forbidden argument/return types.
-     *
-     * @remarks
-     * - They may not be referenced in AnQst specs or imported types.
-     * - Service methods cannot accept them as arguments
-     * - Service methods cannot return them.
-     * - Service properties of their type cannot be declared.
-     *
-     * - For Objects/Maps/Sets use AnQst.Type.<Type> instead.
-     */
-    export enum ForbiddenType {
-        Function = "Passing callbacks across the boundary is not allowed.",
-        Class = "Passing classes across the boundary is not allowed.",
-        Type = "Passing types across the boundary is not allowed.",
-        Promise = "Passing Promises across the boundary is not allowed",
-        Callable = "Passing Callable objects across the boundary is not allowed",
-        any = "Passing 'any' type across the boundary is not allowed",
-    }
-
-    /**
-     * JS/TS Error instances can be returned, but they have special meaning.
-     *
-     * @remarks
-     * AnQst is opinionated, Errors are not for control flow. They are for signalling unrecoverable and unhandled circumstance.
-     * Use: To indicate unrecoverable program error/wrong use.
-     * Don't use: To communicate expected and/or ignorable/handable situations, define a domain-specific transport type instad.
-     * When else encountered: Unhandled Errors.
-     * Effect: The receiving end throws an exception with message `<service>.<member> emitted error: <WidgetStackTrace>`
-     * AnQst internal behavior:
-     * When AnQst type translation/mapping encounters a true Error object instance, the Error object is not transported, instead
-     * the sending AnQst code signals to the receiving AnQst code a message, and the receiving AnQst code throws a runtime exception on
-     * the call or callback site in the Parent.
-
-     */
-    export enum ExceptionalType {
-        Error = "AnQst will not transport an Error object, but will cause an exception to be thrown on reception site."
-    }
-
-}
-
+/**
+ * AnQst-Spec Language - Canonical source of truth for the language.
+ *
+ * @remarks
+ * - DSL for Widget generation, transported as TypeScript definition.
+ * - For AnQSt Widget Specifications only.
+ * - Exactly one toplevel namespace must be declared: It names the Widget.
+ * - Service interfaces are optional. Namespace-local type declarations are valid generation roots.
+ * - Imported/external types are generation-relevant when transitively reachable from namespace declarations.
+ * - This is not an input file to the generator, it is the description of the language that describes the widget.
+ *   Not for use by TypeScript application implementation.
+ * @example
+ * package.json:
+ * - "AnQst": "./AnQst/MyUserMgmtWidget.settings.json"
+ */
+
+export namespace AnQst {
+
+    /**
+     * Declare service `InterfaceName`
+     * 
+     * @remarks
+     * Multiple allowed.
+     * Affords developers of advanced widgets the ability to create domain-informed categories.
+     * - Duplicate method declarations with identical parameter lists are invalid in normative AnQst-Spec input.
+     * 
+     * @example
+     * export interface UserService extends Widget.Service { }
+     * // Generates UserService.
+     */
+    interface Service { }
+
+    /**
+     * Declare service `InterfaceName` as development-mode capable transport service.
+     *
+     * @remarks
+     * - Extends the same method/property semantics as `AnQst.Service`.
+     * - Signals to the generator/runtime that this widget should emit dual-transport bridge support
+     *   (Qt WebChannel + HTTP/WebSocket development bridge).
+     * - Existing generated service APIs remain unchanged.
+     *
+     * @example
+     * export interface UserService extends AnQst.AngularHTTPBaseServerClass { }
+     */
+    interface AngularHTTPBaseServerClass extends Service { }
+
+    type CallConfig = { timeoutSeconds: number } | { timeoutMilliseconds: number } | {};
+
+    /**
+     * Declare non-blocking service method `MethodName`(`MethodArguments`): Promise<`MethodReturnType`>.
+     * @remarks
+     * - **Widget** -> Parent
+     * - Flow:
+     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
+     *   - Widget: Returns Promise<`MethodReturnType`>.
+     *   - Parent: Registered callback receives args and returns `T` synchronously.
+     *   - Widget: Promise resolves with payload `T` or rejects with plain error object.
+     * - Optional config supports timeout tuning:
+     *   - `AnQst.Call<T, { timeoutSeconds: N }>`
+     *   - `AnQst.Call<T, { timeoutMilliseconds: N }>`
+     * - Exactly one timeout key is allowed. Value must be integer >= 0.
+     * - Default timeout is 120s. `0` means wait forever.
+     * @example
+     * // AnQst spec:
+     * getUserById(userId: string): AnQst.Call<User>
+     * //Angular app:
+     * const user: User = await this.userService.getUserById("abc");
+    */
+    interface Call<T, Config extends CallConfig = {}> { dummy: T; config?: Config }
+
+    /**
+     * Declare blocking service method onSlot.`MethodName`( handler(`MethodArguments`):`MethodReturnType` ): void
+     * @remarks
+     * - **Parent** -> Widget
+     * - Impl note: Autogenerated stub handler queues until handler is set (set method calls spools queue through handler)
+     * - Flow:
+     *   - Parent: Call to generated widget method `MethodName`(`MethodArguments`).
+     *   - Widget: Registered handler(`MethodArguments`) is called.
+     *   - Widget: Handler return forms:
+     *      - `T` -> success payload
+     *      - `Promise<T>` -> awaited, success payload on resolve
+     *      - `Error` -> failure
+     *      - throw -> failure
+     *      - rejected promise -> failure
+     *   - Parent: `MethodName` call returns with result.
+     * - Default Slot timeout is 1000ms.
+     * Note: One active handler, calling will replace existing and is valid and allowed.
+     * @example
+     * // AnQst spec:
+     * getUsernameSubstring(from: number, to:number ): AnQst.Slot<string>
+     * //Angular app:
+     * this.userService.onSlot.getUsername( provider );
+     * //Parent:
+     * auto currentFormUsername = userMgmt.getUsername();
+    */
+    interface Slot<T> { dummy: T }
+
+
+
+    /**
+     * Declare message emission method `MethodName`(`MethodArguments`): void
+     * @remarks
+     * - **Widget** -> ?Parent
+     * True Qt signal semantics (Message is emitted, no return path, no registration requirement)
+     * - Flow:
+     *   - Widget: Call to service method `MethodName`(`MethodArguments`).
+     *   - Widget: Returns void.
+     *   - Parent: Might have something connected to the signal, might not.
+     * - If no listener is connected, event is dropped.
+     * @example
+     * // AnQst spec:
+     * complain(whine: string): AnQst.Emitter;
+     * //Angular app:
+     * this.userService.complain("Why won't you LISTEN!");
+    */
+    interface Emitter { }
+
+
+    /**
+     * Declare reactive `PropertyName`:`OutputType` and set.`PropertyName`(arg: `OutputType`)
+     * @remarks
+     * - **Parent** -> Widget
+     * True Angular signal semantics (Property updates, signal emits, no return path, no registration requirement)
+     * - Flow:
+     *   - Parent: Sets generated widget property `PropertyName`.
+     *   - Widget: Service updates readonly property `PropertyName` and emits signal.
+     * @example
+     * // AnQst spec:
+     * activeUsers: AnQst.Output<number>;
+     * //Angular app template:
+     * <p>{{ userService.activeUsers() }}</p>
+     * //Parent:
+     * int users = userMgmt.activeUsers;
+     * userMgmt.activeUsers = 99;
+     */
+    interface Output<OutputType> {}
+
+
+    /**
+     * Declare Input bindable set.`PropertyName`(input:`InputType`): void and `PropertyName`:`InputType`
+     * @remarks
+     * - **Widget** -> Parent
+     * - Convenience method, for symmetry with Output.
+     * - Flow:
+     *   - Widget: Calls service set.`PropertyName`(`InputType`) to publish current value.
+     *   - Parent: Mirrored generated widget property `PropertyName` is updated and emits change notification.
+     * @example
+     * // AnQst spec:
+     * currentUsername: AnQst.Input<string>;
+     * //Angular app template:
+     * <input type="text" placeholder="Your Name Here" (input)="userService.set.currentUsername(($event.target as HTMLInputElement).value)" />
+     * //Parent:
+     * QString userName = userMgmt.currentUsername;
+     */
+    interface Input<InputType> {}
+
+
+    /**
+     * Declare drop-target `PropertyName`:`PayloadType`
+     * @remarks
+     * - **Parent** -> Widget (framework-mediated)
+     * - True Angular signal semantics.
+     * - Flow:
+     *   - External: A Qt widget initiates a QDrag carrying QMimeData.
+     *   - Parent: AnQstWebHostBase intercepts the drop via event filter on the
+     *     embedded QWebEngineView's rendering surface.
+     *   - Parent: QMimeData for the accepted format is deserialized (JSON) into
+     *     the generated C++ struct and forwarded through the bridge.
+     *   - Widget: Service updates signal `PropertyName` with the deserialized
+     *     payload and drop coordinates. Angular components react via effect() / template binding.
+     * - MIME type is convention-derived: `application/anqst-dragdropevent_<ServiceName>-<TypeName>`.
+     * - The source QWidget must serialize the drag payload as JSON under the same MIME type.
+     * - Multiple DropTarget members per service are allowed (each accepting a different type).
+     * @example
+     * // AnQst spec:
+     * trackDropped: AnQst.DropTarget<Track>;
+     * // Angular app:
+     * effect(() => {
+     *   const drop = this.service.trackDropped();
+     *   if (drop !== null) { console.log(drop.payload, drop.x, drop.y); }
+     * });
+     */
+    interface DropTarget<T> { dummy: T }
+
+
+    /**
+     * Declare hover-target `PropertyName`:`PayloadType`
+     * @remarks
+     * - **Parent** -> Widget (framework-mediated)
+     * - True Angular signal semantics.
+     * - Flow:
+     *   - External: A Qt widget initiates a QDrag carrying QMimeData.
+     *   - Parent: AnQstWebHostBase intercepts drag-move events via event filter on the
+     *     embedded QWebEngineView's rendering surface. Events are throttled (trailing edge).
+     *   - Parent: Payload is deserialized once on DragEnter; subsequent DragMove events
+     *     forward only the updated position.
+     *   - Widget: Service updates signal `PropertyName` with the payload and current
+     *     coordinates. Signal becomes null on DragLeave.
+     * - Shares the same MIME type convention as DropTarget: `application/anqst-dragdropevent_<ServiceName>-<TypeName>`.
+     * - A HoverTarget without a corresponding DropTarget means "show previews but reject the drop".
+     * - Optional config supports throttle tuning:
+     *   - `AnQst.HoverTarget<T, { maxRateHz: N }>` — maximum rate of hover position updates
+     *     forwarded across the bridge, in hertz. The generator converts this to a millisecond
+     *     interval at build time (e.g. 60 Hz -> 17 ms, 10 Hz -> 100 ms).
+     *   - Default is 60 Hz (~17 ms throttle interval).
+     *   - `0` means no throttling: every QDragMoveEvent is forwarded immediately.
+     *   - There is no upper bound on the value.
+     * @example
+     * // AnQst spec (default 60 Hz throttle):
+     * trackHovering: AnQst.HoverTarget<Track>;
+     * // AnQst spec (custom 10 Hz throttle):
+     * trackHovering: AnQst.HoverTarget<Track, { maxRateHz: 10 }>;
+     * // AnQst spec (no throttling):
+     * trackHovering: AnQst.HoverTarget<Track, { maxRateHz: 0 }>;
+     * // Angular app:
+     * effect(() => {
+     *   const hover = this.service.trackHovering();
+     *   if (hover !== null) { highlight(document.elementFromPoint(hover.x, hover.y)); }
+     * });
+     */
+
+    /**
+     * Configuration for HoverTarget throttle behavior.
+     * @remarks
+     * - `maxRateHz` — Maximum rate in hertz at which hover position updates are forwarded.
+     *   - Default (omitted or `{}`): 60 Hz.
+     *   - `0`: No throttling; every QDragMoveEvent is forwarded.
+     *   - No upper bound.
+     *   - Value must be a numeric literal >= 0.
+     */
+    type HoverTargetConfig = { maxRateHz: number } | {};
+    interface HoverTarget<T, Config extends HoverTargetConfig = {}> { dummy: T; config?: Config }
+
+
+
+    /**
+     * AnQst-Spec type mapping overview and control.
+     *
+     * @remarks
+     * Any Type that be mapped between TypeScript and Qt, C++ standard types or
+     *     Plain Old Data (POD) types (in that order of preference) will be mapped by default.
+     *
+     * Canonical mapping directive namespace is AnQst.Type.<type>.
+     * To express advisory mapping preference, use AnQst.Type.<type>.
+     * Advisory means generator SHOULD honor it, but MAY fall back to inferred/default mapping and emit diagnostic.
+     * Array forms are equivalent: T[] == Array<T>, and AnQst.Type.X[] == Array<AnQst.Type.X>.
+     *
+     * TypeScript definitions+classes and C++ structs are generated for each
+     *     structured TypeScript type ( type = {...} or interface { ... } )
+     *     referenced in an AnQst spec.
+     *
+     */
+    enum Type {
+        object = "JavaScript Object <-> QVariantMap (JSON.stringify/parse semantics)",
+        json  = "JavaScript Object <-> QJsonObject (JSON.stringify/parse semantics)",
+        string = "JavaScript String <-> QString",
+        stringArray = "JavaScript String[] <-> QStringList",
+        number = "JavaScript Number <-> double",
+        qint64 = "JavaScript BigInt <-> qint64 (Default, for symmetry, same as direct use of <BigInt> which is allowed.)",
+        quint64 = "JavaScript BigInt <-> quint64",
+        qint32 = "JavaScript Number <-> qint32",
+        quint32 = "JavaScript Number <-> quint32",
+        qint16 = "JavaScript Number <-> qint16",
+        quint16 = "JavaScript Number <-> quint16",
+        qint8 = "JavaScript Number <-> qint8",
+        quint8 = "JavaScript Number <-> quint8",
+        int32 = "JavaScript Number <-> int32_t",
+        uint32 = "JavaScript Number <-> uint32_t",
+        int16 = "JavaScript Number <-> int16_t",
+        uint16 = "JavaScript Number <-> uint16_t",
+        int8 = "JavaScript Number <-> int8_t",
+        uint8 = "JavaScript Number <-> uint8_t",
+        buffer = "JavaScript ArrayBuffer <-> QByteArray (Default, for symmetry, same as direct use of <ArrayBuffer> which is allowed.)",
+        blob = "JavaScript ArrayBuffer <-> QByteArray",
+        typedArray = "JavaScript TypedArray <-> QByteArray",
+        uint8Array = "JavaScript Uint8Array <-> QByteArray",
+        int8Array = "JavaScript Int8Array <-> QByteArray",
+        uint16Array = "JavaScript Uint16Array <-> QByteArray",
+        int16Array = "JavaScript Int16Array <-> QByteArray",
+        uint32Array = "JavaScript Uint32Array <-> QByteArray",
+        int32Array = "JavaScript Int32Array <-> QByteArray",
+        float32Array = "JavaScript Float32Array <-> QByteArray",
+        float64Array = "JavaScript Float64Array <-> QByteArray",
+    }
+
+
+    /**
+     * These are explicitly forbidden argument/return types.
+     *
+     * @remarks
+     * - They may not be referenced in AnQst specs or imported types.
+     * - Service methods cannot accept them as arguments
+     * - Service methods cannot return them.
+     * - Service properties of their type cannot be declared.
+     *
+     * - For Objects/Maps/Sets use AnQst.Type.<Type> instead.
+     */
+    export enum ForbiddenType {
+        Function = "Passing callbacks across the boundary is not allowed.",
+        Class = "Passing classes across the boundary is not allowed.",
+        Type = "Passing types across the boundary is not allowed.",
+        Promise = "Passing Promises across the boundary is not allowed",
+        Callable = "Passing Callable objects across the boundary is not allowed",
+        any = "Passing 'any' type across the boundary is not allowed",
+    }
+
+    /**
+     * JS/TS Error instances can be returned, but they have special meaning.
+     *
+     * @remarks
+     * AnQst is opinionated, Errors are not for control flow. They are for signalling unrecoverable and unhandled circumstance.
+     * Use: To indicate unrecoverable program error/wrong use.
+     * Don't use: To communicate expected and/or ignorable/handable situations, define a domain-specific transport type instad.
+     * When else encountered: Unhandled Errors.
+     * Effect: The receiving end throws an exception with message `<service>.<member> emitted error: <WidgetStackTrace>`
+     * AnQst internal behavior:
+     * When AnQst type translation/mapping encounters a true Error object instance, the Error object is not transported, instead
+     * the sending AnQst code signals to the receiving AnQst code a message, and the receiving AnQst code throws a runtime exception on
+     * the call or callback site in the Parent.
+
+     */
+    export enum ExceptionalType {
+        Error = "AnQst will not transport an Error object, but will cause an exception to be thrown on reception site."
+    }
+
+}
+