obsbot-mcp 0.4.0 → 0.5.0

package/dist/geometry/aim.js

@@ -0,0 +1,276 @@
+// Pure geometry for aiming the gimbal at a point seen in a snapshot. No I/O, no
+// transport, no device access — everything here is a function of its arguments,
+// which is what makes it testable with no camera attached.
+//
+// Degrees in the public API (matching every other angle in this codebase),
+// radians internal only.
+const toRad = (deg) => (deg * Math.PI) / 180;
+const toDeg = (rad) => (rad * 180) / Math.PI;
+/**
+ * Horizontal field of view of the CAPTURE STREAM for each FOV setting, in
+ * degrees — DERIVED, not three separate measurements.
+ *
+ * Earlier revisions carried wide/medium/narrow as three independently measured
+ * absolutes at +/-3 degrees each. That threw away the most precise thing known
+ * about them: the RATIOS between the modes are measured to ~0.05%, roughly 60x
+ * better than any of the absolutes, so three free values let the modes drift out
+ * of proportion with each other for no reason.
+ *
+ * One anchor plus measured magnifications instead. The anchor's uncertainty
+ * still propagates, but it now moves all three together, which is the honest
+ * representation of what is known.
+ *
+ * MEASURED 2026-07-25 by solving the camera intrinsics from pure gimbal
+ * rotations. A camera that only rotates induces an exact homography
+ * H = K R K^-1 between views, with no dependence on scene depth, so frames at
+ * known gimbal angles determine the focal lengths outright. No distance is
+ * measured anywhere — the gimbal angle is the ruler. That is what makes this
+ * tighter than the tape-measured letter sheet behind the old +/-3 degrees.
+ *
+ * Six rotations (pitch +/-10, +/-20; yaw +/-10) over a static scene, 313-1243
+ * inliers each, gave fx = 1452-1455 px on a 1920-wide frame across every subset
+ * — a spread of 0.2% — which is HFOV 66.84-66.90. Rounded to 67. This also
+ * independently reproduces an earlier pan-and-track measurement of 66.4.
+ *
+ * The per-mode magnifications come from fitting a similarity transform between
+ * frames at each setting on a fixed scene (275 and 683 inliers, 0.48 and 0.44 px
+ * residual). They are pure ratios, so they are unaffected by which capture
+ * format the measurement went through — which matters, because the 1080p pixel
+ * formats do NOT share a field of view (see the note on the capture path below).
+ *
+ * Verified head-to-head on hardware, same feature and same start pose with only
+ * the constant differing: a target at u = +0.91 left a yaw residual of -0.823
+ * degrees under the old 68 and -0.274 under 67.
+ *
+ * CAPTURE FORMAT WARNING: MJPEG 1920x1080 is a 1.201x crop of YUYV 1920x1080 on
+ * this camera — same resolution, different window onto the sensor. These
+ * constants describe the WIDE field, which is what `obsbot_capture_snapshot`
+ * delivers. `obsbot_capture_preview` pins MJPEG and therefore shows ~20% less.
+ * Any future measurement through ffmpeg must state its pixel format; a
+ * resolution alone does not identify the field.
+ *
+ * SCOPE: 16:9 capture at any resolution. A 4:3 path would need re-measuring.
+ */
+export const WIDE_HFOV_DEG = 67;
+/**
+ * Linear magnification of each FOV setting relative to the wide field.
+ *
+ * MEASURED 2026-07-25. These are the precise part of the pair: the ratios are
+ * good to ~0.05% where the anchor above is good to perhaps 0.5%.
+ *
+ * The continuous zoom writes to this same scale rather than multiplying on top
+ * of it — `narrow` plus zoom ratio 1.5 measures 2.509, the same as `wide` plus
+ * 1.5 (2.501), not 1.47 x 2.5. The discrete modes and the zoom control are two
+ * ways of writing to one magnification scale, which is why setting zoom ratio
+ * 1.0 does not reliably clear `custom`: it is the same optical state as `wide`.
+ */
+export const FOV_MAGNIFICATION = {
+    wide: 1,
+    medium: 1.15060,
+    narrow: 1.47073,
+};
+export const HORIZONTAL_FOV_DEG = {
+    wide: 2 * toDeg(Math.atan(Math.tan(toRad(WIDE_HFOV_DEG / 2)) / FOV_MAGNIFICATION.wide)),
+    medium: 2 * toDeg(Math.atan(Math.tan(toRad(WIDE_HFOV_DEG / 2)) / FOV_MAGNIFICATION.medium)),
+    narrow: 2 * toDeg(Math.atan(Math.tan(toRad(WIDE_HFOV_DEG / 2)) / FOV_MAGNIFICATION.narrow)),
+};
+/**
+ * Empirical correction applied on top of the aspect-derived vertical half-angle.
+ * MEASURED, not geometric.
+ *
+ * Square-pixel geometry says tan(V) = tan(H) * (height/width) — 0.5625 at 16:9.
+ * Hardware says the vertical field is shorter than that; this factor carries the
+ * difference.
+ *
+ * MEASURED 2026-07-25 from the same intrinsics solve as WIDE_HFOV_DEG above.
+ * fy came out 1502-1520 px across every subset of six rotations, implying this
+ * factor at 0.957-0.967. Rounded to 0.957.
+ *
+ * This REPLACES an earlier value of 0.898, which was 7% low. That figure came
+ * from a measurement this project's own history recorded as inconclusive: the
+ * constant itself was off by about 6.2%, versus the ~4.3% effect it was trying
+ * to capture — roughly 1.4x the effect itself, not an order of magnitude off.
+ *
+ * The up/down asymmetry is ~1%, not the ~5% once believed: solving from the
+ * up-tilt alone gives 0.957 and from the down-tilt alone 0.967. One constant
+ * captures that comfortably. Do NOT reintroduce a two-branch vertical constant
+ * on the strength of the old figure. Both candidate explanations for a genuine
+ * asymmetry were tested and eliminated — the principal point is centred (cx, cy
+ * within a few px of frame centre in every solve) and radial distortion is
+ * negligible (k1 ~= -0.02).
+ *
+ * Verified head-to-head on hardware, same feature and same start pose with only
+ * this constant differing: a target at v = -0.83 left a pitch residual of -0.597
+ * degrees under 0.898 and +0.072 under 0.957, an 8x improvement that lands
+ * inside the noise.
+ *
+ * Known limit: the intrinsics fit carries 2.4-2.8 px rms, not sub-pixel, so
+ * something is unmodelled — most likely the entrance pupil sitting off the
+ * gimbal's rotation axes, which translates the lens as it turns and is
+ * depth-dependent. Sampling was symmetric so it should not bias fx or fy, but do
+ * not claim more precision than that.
+ *
+ * SCOPE: measured on the 16:9 capture path. A 4:3 path needs its own measurement.
+ */
+export const VERTICAL_TANGENT_CORRECTION = 0.957;
+// The tangents are the useful form for every downstream calculation, so they are
+// computed once here and the degree-valued halfAngles() is a thin wrapper. Going
+// through degrees would mean an atan followed immediately by a tan.
+const halfAngleTangents = (optics, frame) => {
+    const zoom = optics.zoom ?? 1;
+    const tanH = Math.tan(toRad(HORIZONTAL_FOV_DEG[optics.fov] / 2)) / zoom;
+    // Vertical starts from the horizontal half-angle scaled by the frame aspect —
+    // what square-pixel geometry predicts — then takes the measured correction,
+    // because hardware says the real vertical field is ~4.3% shorter than that.
+    // See VERTICAL_TANGENT_CORRECTION for the intrinsics solve over six gimbal
+    // rotations behind it.
+    return { tanH, tanV: tanH * (frame.height / frame.width) * VERTICAL_TANGENT_CORRECTION };
+};
+/** Effective half-angles of the visible field, in degrees, after zoom and aspect. */
+export function halfAngles(optics, frame) {
+    const { tanH, tanV } = halfAngleTangents(optics, frame);
+    return { h: toDeg(Math.atan(tanH)), v: toDeg(Math.atan(tanV)) };
+}
+/**
+ * Convert a pixel in a captured frame to the yaw/pitch delta that would bring
+ * that point to the center of frame, treating each axis independently.
+ *
+ * PER-AXIS ONLY — this does NOT account for axis coupling. The gimbal's yaw
+ * axis is world-vertical, so yawing while pitched sweeps a cone; the two axes
+ * commute only at zero pitch or zero horizontal offset (see `aimAtPixel`,
+ * which composes a rotation instead and is what every tool actually points
+ * the camera with). Adding this function's dYaw/dPitch to a pose that is not
+ * level reproduces the additive bug `aimAtPixel` was fixed to remove. It is
+ * used only by tests now, to pin the per-axis tangent mapping in isolation
+ * from the coupling — do not reach for it as a general "point the camera"
+ * answer.
+ *
+ * A rectilinear lens maps angle through a tangent: tan(theta) = u * tan(hfov/2),
+ * where u is the normalized offset from center. The linear approximation is
+ * exact at the center and again at the edge, and wrong in between — always low,
+ * peaking near 1.58 degrees at u ~= 0.55 on the wide setting (WIDE_HFOV_DEG =
+ * 67). That error is the difference between landing on target and visibly
+ * hunting, so the tangent form is not optional.
+ *
+ * Signs: +yaw pans camera-LEFT and image x grows rightward, so the yaw term is
+ * negated. +pitch tilts DOWN and image y grows downward, so the pitch term is
+ * not. Both conventions are hardware-verified.
+ */
+export function pixelToOffset(x, y, frame, optics) {
+    const { tanH, tanV } = halfAngleTangents(optics, frame);
+    const u = (2 * x) / frame.width - 1;
+    const v = (2 * y) / frame.height - 1;
+    const uEff = optics.mirrored ? -u : u;
+    return {
+        dYaw: -toDeg(Math.atan(uEff * tanH)),
+        dPitch: toDeg(Math.atan(v * tanV)),
+    };
+}
+/**
+ * Mechanical limits of the Tiny 2's gimbal, in degrees. Hardware-verified.
+ *
+ * These live here rather than in the tool layer so there is exactly one
+ * definition: `obsbot_gimbal_move` imports them for its own clamping. Two copies
+ * of a bound that must agree is a defect waiting to happen.
+ *
+ * ±150 is the mechanical yaw range on EVERY platform, and these limits are not
+ * platform-conditional. Measured 2026-07-25: commanded 145 reads back 145, and
+ * 150 reads back 149. Position feedback comes from the camera's physical
+ * encoder, which is a property of the hardware and does not vary by OS.
+ *
+ * Do not "fix" this to 130. `transport/linux.ts` and `transport/macos.ts` record
+ * a `CT_PANTILT_ABSOLUTE` range of ±468000 arcsec = ±130°, which reads like a
+ * conflict and was raised as one during review. It is not: that is the range the
+ * UVC control *advertises* — a descriptor value that under-reports the mechanism
+ * it describes — not where the gimbal stops. Nothing clamps to it either;
+ * `LinuxTransport.gimbalSet` writes `yawDeg * ARCSEC_PER_DEG` unclamped, so the
+ * arcsec figure lives only in comments. See the spec's §8.
+ */
+export const GIMBAL_YAW_LIMIT_DEG = 150;
+export const GIMBAL_PITCH_LIMIT_DEG = 90;
+const clampTo = (value, limit) => Math.min(limit, Math.max(-limit, value));
+/**
+ * Absolute pose that brings the given pixel to the centre of frame.
+ *
+ * Composes a rotation rather than adding two scalars. The gimbal's yaw axis is
+ * world-vertical, so yawing while pitched sweeps a CONE: the two rotations do
+ * not commute, and `target = current + offset` is exact only at zero pitch or
+ * zero horizontal offset. Adding them cost 0.98 degrees at pitch 7.6 / yaw 31 on
+ * hardware, against `pitch * (1 - cos yaw)` = 1.09 predicted.
+ *
+ * The ray to the target in camera coordinates (x right, y down, z forward) is
+ * rotated into world coordinates by the current orientation, and the target pose
+ * is read back off that direction. The two axes reduce to the old additive sum
+ * under DIFFERENT conditions, not the same one: yaw reduces exactly to the old
+ * sum whenever pitch = 0, for any pixel, because yaw and pitch commute at zero
+ * tilt. Pitch reduces to the old sum only when u = 0 (the pixel sits on the
+ * vertical centre line) — composed pitch is asin(dy/n) where n includes dx, so
+ * away from u = 0 it differs from the old atan(dy) even when pitch is 0. That is
+ * what the invariant tests pin.
+ *
+ * Saturation is REPORTED, not silent: if the target lies outside the gimbal's
+ * range the caller has to know it landed short rather than assume the aim
+ * succeeded, since a silent clamp presents as "the camera aimed and missed".
+ *
+ * `current` must be where the camera actually was when the frame was captured.
+ * The module cannot verify that — see the spec's section 5 for what breaks it.
+ * Note that on Windows the pose the caller reads is FLOORED to whole degrees
+ * (spec section 4.2), which costs up to another degree; that is a separate
+ * defect in the pose source, not in this function.
+ */
+export function aimAtPixel(x, y, frame, optics, current) {
+    const { tanH, tanV } = halfAngleTangents(optics, frame);
+    const u = (2 * x) / frame.width - 1;
+    const v = (2 * y) / frame.height - 1;
+    const uEff = optics.mirrored ? -u : u;
+    // Ray to the target, in camera coordinates: x right, y down, z forward.
+    const dx = uEff * tanH;
+    const dy = v * tanV;
+    const dz = 1;
+    const n = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    const cy = Math.cos(toRad(current.yaw));
+    const sy = Math.sin(toRad(current.yaw));
+    const cp = Math.cos(toRad(current.pitch));
+    const sp = Math.sin(toRad(current.pitch));
+    // Pitch first, about the camera's own x-axis (+pitch tilts DOWN)...
+    const px = dx / n;
+    const py = (dy * cp + dz * sp) / n;
+    const pz = (-dy * sp + dz * cp) / n;
+    // ...then yaw, about the world vertical (+yaw pans camera-LEFT).
+    const wx = px * cy - pz * sy;
+    const wy = py;
+    const wz = px * sy + pz * cy;
+    const rawPitch = toDeg(Math.asin(Math.max(-1, Math.min(1, wy))));
+    // atan2 returns [-180, 180] — -180 IS included, and is exactly the case the
+    // following paragraph handles. Pick the representative nearest the current
+    // yaw so a target past +150 reads as +183 rather than -177. Without this a
+    // saturating aim clamps to the WRONG END of the range.
+    //
+    // This is a modulo wrap rather than `Math.round((current.yaw - rawYaw) /
+    // 360)`: at an exact 180-degree difference — dead behind the camera, which
+    // happens for real at u = 0 aiming past vertical — that rounds ties toward
+    // +Infinity regardless of sign (JS's Math.round(0.5) is 1, not 0), which
+    // silently flips -180 to +180 and clamps on the wrong end. The wrap below
+    // always resolves an exact tie to the lower edge of the window instead.
+    const rawYawAtan2 = toDeg(Math.atan2(-wx, wz));
+    const rawYaw = current.yaw + (((rawYawAtan2 - current.yaw + 180) % 360 + 360) % 360 - 180);
+    const yaw = clampTo(rawYaw, GIMBAL_YAW_LIMIT_DEG);
+    const pitch = clampTo(rawPitch, GIMBAL_PITCH_LIMIT_DEG);
+    // Over the top: the target ray's horizontal direction points opposite the
+    // camera's current heading. (hx, hz) is that heading; (wx, wz) is the target
+    // direction, both already computed above. A negative dot product means the
+    // only way to face the target while keeping the image upright is to go past
+    // vertical — clamping the resulting yaw to the nearest limit would slew the
+    // camera toward the OPPOSITE side of the room, not toward the target, so the
+    // caller must refuse this case rather than clamp-and-move it.
+    const hx = -sy;
+    const hz = cy;
+    const overTheTop = hx * wx + hz * wz < 0;
+    return {
+        target: { yaw, pitch },
+        offset: { dYaw: rawYaw - current.yaw, dPitch: rawPitch - current.pitch },
+        clamped: yaw !== rawYaw || pitch !== rawPitch,
+        overTheTop,
+    };
+}
+//# sourceMappingURL=aim.js.map

package/dist/geometry/aim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aim.js","sourceRoot":"","sources":["../../src/geometry/aim.ts"],"names":[],"mappings":"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"}

package/dist/mcp/ready.d.ts

@@ -15,6 +15,7 @@ export type ReadyResult = {
     ok: true;
     transport: ObsbotTransport;
     reconnected: boolean;
+    woke: boolean;
 } | {
     ok: false;
     reason: "unreachable" | "wake-timeout";

package/dist/mcp/ready.js

@@ -48,7 +48,9 @@ export async function ensureReady(getTransport, reconnect, opts = {}) {
             return { ok: false, reason: "unreachable", error: `camera not reachable: ${msg(e2)}` };
         }
     }
+    let woke = false;
     if (!awake) {
+        woke = true;
         await t.sendVendor(encodeSetRunStatus("run").buildFrame(t.nextSeq()));
         let waited = 0;
         while (waited < wakeTimeoutMs) {
@@ -69,6 +71,6 @@ export async function ensureReady(getTransport, reconnect, opts = {}) {
         }
         await sleep(settleMs); // let the gimbal finish rising before we drive it
     }
-    return { ok: true, transport: t, reconnected: reconnect?.takeReconnected() ?? false };
+    return { ok: true, transport: t, reconnected: reconnect?.takeReconnected() ?? false, woke };
 }
 //# sourceMappingURL=ready.js.map

package/dist/mcp/ready.js.map

@@ -1 +1 @@
-{"version":3,"file":"ready.js","sourceRoot":"","sources":["../../src/mcp/ready.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AA0B1D,MAAM,QAAQ,GAAwB,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AAE1F,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AACnF,gFAAgF;AAChF,gFAAgF;AAChF,gDAAgD;AAChD,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAU,EAAU,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAExF,MAAM,SAAS,GAAG,KAAK,EAAE,CAAkB,EAAoB,EAAE,CAC/D,YAAY,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,YAA4C,EAC5C,SAAwB,EACxB,OAAkB,EAAE;IAEpB,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;IAErE,IAAI,CAAkB,CAAC;IACvB,IAAI,CAAC;QACH,CAAC,GAAG,MAAM,YAAY,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,qBAAqB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpF,CAAC;IAED,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,oEAAoE;QACpE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,yBAAyB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACxF,CAAC;QACD,MAAM,SAAS,CAAC,UAAU,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,CAAC,GAAG,MAAM,YAAY,EAAE,CAAC;YACzB,KAAK,GAAG,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,EAAE,EAAE,CAAC;YACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,yBAAyB,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzF,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACtE,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,OAAO,MAAM,GAAG,aAAa,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;YACpB,MAAM,IAAI,MAAM,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,MAAM,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;oBACvB,KAAK,GAAG,IAAI,CAAC;oBACb,MAAM;gBACR,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,+DAA+D;YACjE,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;QAC5F,CAAC;QACD,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,kDAAkD;IAC3E,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,IAAI,KAAK,EAAE,CAAC;AACxF,CAAC"}
+{"version":3,"file":"ready.js","sourceRoot":"","sources":["../../src/mcp/ready.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.js

@@ -71,7 +71,7 @@ export async function startServer(opts = {}) {
     process.on("SIGTERM", () => { shutdown(); process.exit(0); });
     const server = new Server(
     // Must match package.json's version; test/version-sync.test.ts enforces it.
-    { name: "obsbot-mcp", version: "0.4.0" }, { capabilities: { tools: {} } });
+    { name: "obsbot-mcp", version: "0.5.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((tool) => ({
             name: tool.name,

package/dist/mcp/tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { encodeSetRunStatus, zoomRatioToUnits, encodeAiTrackSpeed, encodeAiTracking, encodeAiMode, encodeFaceAe, encodeVendorProbe, encodeVendorGet, encodeZoomWithSpeed, encodeFaceFocus, encodeSetExposure, decodeStatus, encodeFov, encodeHdr, percentToRange, AI_FRAMING_MODES, AI_SCENE_MODES, AI_TRACK_SPEEDS, FOV_TYPES, UVC_XU_SELECTOR, CAMERA_CONTROL_PAN, CAMERA_CONTROL_TILT, CAMERA_CONTROL_FOCUS, VIDEO_PROCAMP_WHITE_BALANCE, IMAGE_CONTROL_PROP, IMAGE_CONTROLS, UVC_FLAG_AUTO, UVC_FLAG_MANUAL, } from "../codec/commands.js";
+import { aimAtPixel, GIMBAL_YAW_LIMIT_DEG, GIMBAL_PITCH_LIMIT_DEG } from "../geometry/aim.js";
 import { verifyFraming } from "./framing.js";
 import { parseFrame } from "../codec/frame.js";
 import { OP_BY_NAME } from "../codec/opcodes.js";
@@ -113,6 +114,12 @@ const imageExposureManualSchema = withCamera({
     level: num().pipe(z.number().min(0).max(100)).default(50),
 });
 const gimbalPositionSchema = withCamera({});
+const aimAtPixelSchema = withCamera({
+    x: num().pipe(z.number().finite()),
+    y: num().pipe(z.number().finite()),
+    frameWidth: num().pipe(z.number().finite().min(1)),
+    frameHeight: num().pipe(z.number().finite().min(1)),
+});
 const presetListSchema = withCamera({});
 const presetSaveSchema = withCamera({
     slot: num().pipe(z.union([z.literal(1), z.literal(2), z.literal(3)])),
@@ -261,6 +268,13 @@ async function getPresetSlots(t) {
 // window. Latency is the cheapest thing we can spend here.
 const PRESET_READ_DEFAULTS = { attempts: 3, backoffMs: [200, 500, 1000] };
 const napMs = (ms) => new Promise((r) => setTimeout(r, ms));
+// Pan/tilt readback is a float now (see transport/linux.ts, transport/macos.ts),
+// which can carry many more digits than the hardware's ±1° accuracy justifies —
+// e.g. 5.975277777777778 from an arc-second division. Round to 2 decimal places
+// for reporting: enough to show sub-degree structure (useful on Linux, where it
+// reflects the last commanded pose) without implying precision the readout
+// doesn't have.
+const round2 = (deg) => Math.round(deg * 100) / 100;
 const allEmpty = (slots) => slots.every((s) => !s.occupied);
 /**
  * Read the preset slots with bounded retry, and confirm the one verdict whose error
@@ -375,13 +389,15 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
         {
             name: "obsbot_gimbal_move",
             description: "Move the gimbal to an absolute yaw/pitch angle (degrees); positive yaw pans to the " +
-                "camera's left, positive pitch tilts down. Yaw is clamped to [-150,150], pitch to " +
-                "[-90,90]. Absolute positioning (1:1 degrees), verified on hardware.",
+                `camera's left, positive pitch tilts down. Yaw is clamped to ` +
+                `[-${GIMBAL_YAW_LIMIT_DEG},${GIMBAL_YAW_LIMIT_DEG}], pitch to ` +
+                `[-${GIMBAL_PITCH_LIMIT_DEG},${GIMBAL_PITCH_LIMIT_DEG}]. ` +
+                "Absolute positioning (1:1 degrees), verified on hardware.",
             schema: ptzMoveAngleSchema,
             handler: async (args) => {
                 const parsed = ptzMoveAngleSchema.parse(args);
-                const yaw = clamp(parsed.yaw, -150, 150);
-                const pitch = clamp(parsed.pitch, -90, 90);
+                const yaw = clamp(parsed.yaw, -GIMBAL_YAW_LIMIT_DEG, GIMBAL_YAW_LIMIT_DEG);
+                const pitch = clamp(parsed.pitch, -GIMBAL_PITCH_LIMIT_DEG, GIMBAL_PITCH_LIMIT_DEG);
                 const roll = parsed.roll;
                 const ready = await gate(parsed.camera);
                 if (!ready.ok)
@@ -545,10 +561,13 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
         },
         {
             name: "obsbot_status",
-            description: "Read the camera's live status block. Returns { awake, hdr, faceAe, aiMode, trackSpeed }: " +
+            description: "Read the camera's live status block. Returns { awake, hdr, faceAe, aiMode, trackSpeed, " +
+                "fovMode, zoomPercent }: " +
                 "faceAe is whether auto-exposure is metering for a detected face; " +
                 "aiMode is the current AI framing (no-tracking|normal|upper-body|close-up|headless|" +
-                "lower-body|desk|whiteboard|hand|group|unknown); trackSpeed is standard|sport|unknown. " +
+                "lower-body|desk|whiteboard|hand|group|unknown); trackSpeed is standard|sport|unknown; " +
+                "fovMode is the field-of-view mode (wide|medium|narrow|custom|unknown), where custom means " +
+                "a continuous zoom overrode the discrete modes; zoomPercent is the zoom position, 0-100. " +
                 "Under --debug the result also carries `raw`: the full 60-byte status block as hex " +
                 "(for reverse-engineering undecoded offsets).",
             schema: getStatusSchema,
@@ -696,7 +715,8 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
             name: "obsbot_gimbal_position",
             description: "Read the gimbal's current absolute yaw/pitch in degrees (positive yaw = camera's " +
                 "left, positive pitch = down) via the standard UVC Pan/Tilt controls. This is a live " +
-                "hardware readout accurate to ±1°: it is valid during a move as well as after one, " +
+                "hardware readout accurate to ±1°, reported rounded to 2 decimal places (finer digits " +
+                "would be noise, not precision): it is valid during a move as well as after one, " +
                 "and reflects motion the host did not command (speed moves, recenter, tracking).",
             schema: gimbalPositionSchema,
             handler: async (args) => {
@@ -706,7 +726,129 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
                 const tilt = await t.camCtrlGet(CAMERA_CONTROL_TILT);
                 // UVC pan value is degrees, same sign as our yaw (+ = camera-left). UVC tilt
                 // is degrees but positive = up, so negate to match our +pitch = down convention.
-                return { yaw: pan.value, pitch: -tilt.value };
+                return { yaw: round2(pan.value), pitch: round2(-tilt.value) };
+            },
+        },
+        {
+            name: "obsbot_aim_at_pixel",
+            description: "Point the camera at a specific pixel in a frame you just captured. Give the pixel's x/y " +
+                "and the frameWidth/frameHeight from THE SAME obsbot_capture_snapshot result — mixing a " +
+                "pixel from one frame with dimensions from another aims at the wrong place and cannot be " +
+                "detected. The frame must come from a source:\"device\" snapshot — virtual and ndi frames " +
+                "are framed by OBSBOT Center, not this camera's own optics, and will aim wrongly. Takes no " +
+                "field-of-view argument: it reads the camera's actual FOV mode. Refuses when AI tracking is " +
+                "active (tracking moves the gimbal itself and would fight the aim) and when a custom zoom " +
+                "is set (the zoom magnification is measured but not applied yet), so it never aims on an assumption it " +
+                "cannot check. If the camera was asleep, waking it moves the gimbal and invalidates the " +
+                "frame you measured, so the call refuses instead of aiming on stale geometry — take a fresh " +
+                "snapshot and retry. Returns clamped:true if the target was outside the gimbal's range; the " +
+                "camera still moves, to the nearest reachable pose. Refuses (ok:false) instead of moving when " +
+                "the pixel lies past vertical from the current pose — reachable only by an \"over the top\" " +
+                "rotation that would swing the camera toward the opposite side of the room, not toward the " +
+                "target; tilt toward the pixel first, then re-aim.",
+            schema: aimAtPixelSchema,
+            handler: async (args) => {
+                const { x, y, frameWidth, frameHeight, camera } = aimAtPixelSchema.parse(args);
+                // 16:9 is preserved by the capture path at every resolution (verified at
+                // 256x144, 1280x720, 1920x1080), so a non-16:9 pair did not come from that
+                // path as-is — it was transposed (width/height swapped) or came from
+                // somewhere else entirely, since passing the values through unchanged
+                // always yields 16:9.
+                if (Math.abs(frameWidth / frameHeight - 16 / 9) > 0.02) {
+                    return {
+                        ok: false,
+                        error: `frame ${frameWidth}x${frameHeight} is not 16:9, but obsbot_capture_snapshot always ` +
+                            `returns 16:9 frames. This looks like frameWidth/frameHeight were transposed, or came ` +
+                            `from something other than that tool's result.`,
+                    };
+                }
+                if (x < 0 || x > frameWidth || y < 0 || y > frameHeight) {
+                    return { ok: false, error: `pixel (${x},${y}) is outside the ${frameWidth}x${frameHeight} frame` };
+                }
+                // The gate wakes a sleeping camera and waits for it to settle. If it had
+                // to wake the camera, the gimbal just moved out from under the frame the
+                // caller measured — refuse below rather than read a pose that no longer
+                // corresponds to that frame.
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                if (ready.woke) {
+                    return {
+                        ok: false,
+                        error: "the camera was asleep and waking it moved the gimbal, so the frame you measured no " +
+                            "longer matches where the camera is pointing. Take a fresh snapshot and aim again.",
+                    };
+                }
+                const block = await t.recvStatus();
+                const status = decodeStatus(block);
+                if (status.aiMode === "unknown") {
+                    return {
+                        ok: false,
+                        error: "could not read the camera's AI-tracking mode (the status block didn't decode this " +
+                            "read — this can happen during a brief mode-switch transient); retry the aim.",
+                    };
+                }
+                if (status.aiMode !== "no-tracking") {
+                    return {
+                        ok: false,
+                        error: `AI tracking is active (${status.aiMode}); it moves the gimbal itself and would ` +
+                            `fight the aim. Disable it with obsbot_ai_track {enabled:false} first.`,
+                    };
+                }
+                if (status.fovMode === "custom") {
+                    return {
+                        ok: false,
+                        error: `a custom zoom is active (zoom ${status.zoomPercent}%). The zoom-to-magnification ` +
+                            `mapping IS measured — magnification is 3*ratio-2, so this zoom is about ` +
+                            `${(1 + 0.03 * status.zoomPercent).toFixed(2)}x — but it is not applied here yet, and ` +
+                            `aiming without it would be wrong by that factor. Set obsbot_image_fov {fov:"wide"} ` +
+                            `(or any discrete mode) to clear it. obsbot_zoom_uvc {ratio:1} will NOT clear it: ` +
+                            `ratio 1.0 is the same optical state as wide, so the camera stays in custom mode.`,
+                    };
+                }
+                if (status.fovMode === "unknown") {
+                    // block[0x11] is STATUS_OFF_FOV_MODE (src/codec/commands.ts) — same offset
+                    // decodeStatus reads to produce fovMode, surfaced raw since "unknown" means
+                    // it didn't match any known value.
+                    return {
+                        ok: false,
+                        error: `could not read the camera's FOV mode (raw byte 0x${block[0x11].toString(16).padStart(2, "0")}); ` +
+                            `refusing to guess it. Set a known mode with obsbot_image_fov (e.g. {fov:"wide"}) and retry.`,
+                    };
+                }
+                // Same read path as obsbot_gimbal_position: UVC pan is degrees with our
+                // yaw sign; UVC tilt is degrees but positive = up, so negate it.
+                const yaw = (await t.camCtrlGet(CAMERA_CONTROL_PAN)).value;
+                const pitch = -(await t.camCtrlGet(CAMERA_CONTROL_TILT)).value;
+                // zoom:1 — the measured FOV constants already include each discrete
+                // mode's inherent crop, so applying zoomPercent again would double-count.
+                const aim = aimAtPixel(x, y, { width: frameWidth, height: frameHeight }, { fov: status.fovMode, zoom: 1 }, { yaw, pitch });
+                // Over the top is not an ordinary clamp: the target ray points behind
+                // the camera's current heading, so the nearest reachable yaw is on the
+                // FAR side of the gimbal's range, not near the target. Moving there
+                // would slew ~150 degrees into the opposite corner of the room while
+                // reporting clamped:true, which reads as "landed short" rather than
+                // "went the wrong way" — refuse instead of moving.
+                if (aim.overTheTop) {
+                    return {
+                        ok: false,
+                        error: `pixel (${x},${y}) lies past vertical from the current pose (yaw ${yaw.toFixed(1)}, ` +
+                            `pitch ${pitch.toFixed(1)}); it is not reachable while keeping the image upright, only ` +
+                            `by an "over the top" rotation that would swing the camera the opposite way. Tilt toward ` +
+                            `the pixel first (e.g. obsbot_gimbal_move), then re-aim from the new pose.`,
+                    };
+                }
+                await t.gimbalSet(aim.target.yaw, aim.target.pitch, 0);
+                return {
+                    ok: true,
+                    target: aim.target,
+                    offset: aim.offset,
+                    clamped: aim.clamped,
+                    fovMode: status.fovMode,
+                    current: { yaw, pitch },
+                    ...(ready.reconnected ? { reconnected: true } : {}),
+                };
             },
         },
         {