obsbot-mcp 0.5.0 → 0.6.0

package/dist/mcp/tools.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { FovType } from "../codec/commands.js";
 import { DeviceManager } from "../device/manager.js";
 import type { CaptureManager } from "../capture/manager.js";
 export interface ToolDef {
@@ -7,8 +8,57 @@ export interface ToolDef {
     schema: z.ZodTypeAny;
     handler: (args: unknown) => Promise<object>;
 }
+/**
+ * Why {@link resolveMagnification} could not resolve a usable magnification.
+ * Carried explicitly rather than left for the caller to re-derive from
+ * `status.fovMode`, because that re-derivation is exactly the trap this type
+ * exists to close: it was correct for the two reasons that existed when it was
+ * written (an "if unknown, else assume corrupt zoom" fallthrough), but is not
+ * exhaustive — a third reason added later would silently be mislabelled as
+ * "implausible-zoom" by every caller doing that inference independently. One
+ * function decides the reason so there is exactly one place that has to be
+ * right.
+ */
+export type MagnificationResult = {
+    ok: true;
+    magnification: number;
+} | {
+    ok: false;
+    reason: "unknown-fov";
+} | {
+    ok: false;
+    reason: "implausible-zoom";
+    zoomPercent: number;
+};
+/**
+ * The camera's total magnification relative to wide, from its reported state.
+ *
+ * A discrete FOV mode and a continuous zoom are two ways of writing to one
+ * scale, so this returns one number either way. Fails (`ok: false`) for
+ * anything that cannot be trusted:
+ *  - `reason: "unknown-fov"` — the status byte didn't decode, a state to
+ *    refuse on rather than guess at.
+ *  - `reason: "implausible-zoom"` — a `"custom"` mode whose derived
+ *    magnification falls outside the camera's known range
+ *    [MIN_MAGNIFICATION, MAX_MAGNIFICATION] — a corrupt or implausible
+ *    `zoomPercent` reading (e.g. a garbled status byte reporting
+ *    zoomPercent > 100). Callers should refuse rather than pass this through:
+ *    the geometry module's own guard (halfAngleTangents in src/geometry/aim.ts)
+ *    would otherwise be the only thing standing between a bad reading and a
+ *    silently wrong — or NaN/Infinity — aim.
+ */
+export declare function resolveMagnification(status: {
+    fovMode: FovType | "custom" | "unknown";
+    zoomPercent: number;
+}): MagnificationResult;
 export interface PresetReadOpts {
     attempts?: number;
     backoffMs?: number[];
 }
-export declare function createTools(mgr: DeviceManager, capture?: CaptureManager, debug?: boolean, presetRead?: PresetReadOpts): ToolDef[];
+export interface ZoomSettleOpts {
+    pollMs?: number;
+    timeoutMs?: number;
+    /** Beat between the two status reads that decide whether the zoom is moving. */
+    motionPollMs?: number;
+}
+export declare function createTools(mgr: DeviceManager, capture?: CaptureManager, debug?: boolean, presetRead?: PresetReadOpts, zoomSettle?: ZoomSettleOpts): ToolDef[];