feat: screenshot APIs accept DOM nodes and jQuery selectors

Add _resolveRect() helper to convert DOM elements and jQuery selector
strings to capture rects, with zoom factor compensation. Update
_capturePageBinary bounds validation to account for webview scale factor.
Add tests for DOM element, selector, and error case inputs.

Author: abose

src/phoenix/shell.js

@@ -147,10 +147,52 @@ Phoenix.libs = {
 // global API is only usable/stable after App init
 Phoenix.globalAPI = {};
 
-async function _capturePageBinary(rect) {
+function _resolveRect(rectOrNodeOrSelector) {
+    if (rectOrNodeOrSelector === undefined || rectOrNodeOrSelector === null) {
+        return undefined; // full page capture
+    }
+    let element;
+    // Case 1: jQuery selector string
+    if (typeof rectOrNodeOrSelector === 'string') {
+        const $el = $(rectOrNodeOrSelector);
+        if ($el.length === 0) {
+            throw new Error("No element found for selector: " +
+                rectOrNodeOrSelector);
+        }
+        if ($el.length > 1) {
+            throw new Error("Selector must match exactly one element, but matched " +
+                $el.length + ": " + rectOrNodeOrSelector);
+        }
+        element = $el[0];
+    } else if (rectOrNodeOrSelector instanceof HTMLElement) {
+        // Case 2: DOM node (Element instance)
+        element = rectOrNodeOrSelector;
+    } else if (typeof rectOrNodeOrSelector === 'object') {
+        // Case 3: Plain rect object {x, y, width, height}
+        return rectOrNodeOrSelector; // pass through for validation in _capturePageBinary
+    } else {
+        throw new Error("Expected a rect object, DOM node, or jQuery selector string");
+    }
+    // Convert DOM element to rect via getBoundingClientRect().
+    // getBoundingClientRect() returns values in the zoomed CSS coordinate space, but
+    // the native capture APIs (Electron capturePage, Tauri capture_page) expect
+    // coordinates in the unzoomed viewport space. Divide by the webview zoom factor
+    // to convert.
+    const zoomFactor = (window.PhStore && window.PhStore.getItem("desktopZoomScale")) || 1;
+    const domRect = element.getBoundingClientRect();
+    return {
+        x: Math.round(domRect.x * zoomFactor),
+        y: Math.round(domRect.y * zoomFactor),
+        width: Math.round(domRect.width * zoomFactor),
+        height: Math.round(domRect.height * zoomFactor)
+    };
+}
+
+async function _capturePageBinary(rectOrNodeOrSelector) {
     if (!Phoenix.isNativeApp) {
         throw new Error("Screenshot capture is not supported in browsers");
     }
+    const rect = _resolveRect(rectOrNodeOrSelector);
     if (rect !== undefined) {
         if (rect.x === undefined || rect.y === undefined ||
             rect.width === undefined || rect.height === undefined) {
@@ -166,10 +208,11 @@ async function _capturePageBinary(rect) {
         if (rect.width <= 0 || rect.height <= 0) {
             throw new Error("rect width and height must be greater than 0");
         }
-        if (rect.x + rect.width > window.innerWidth) {
+        const zoomFactor = (window.PhStore && window.PhStore.getItem("desktopZoomScale")) || 1;
+        if (rect.x + rect.width > window.innerWidth * zoomFactor) {
             throw new Error("rect x + width exceeds window innerWidth");
         }
-        if (rect.y + rect.height > window.innerHeight) {
+        if (rect.y + rect.height > window.innerHeight * zoomFactor) {
             throw new Error("rect y + height exceeds window innerHeight");
         }
     }
@@ -830,18 +873,46 @@ Phoenix.app = {
         }
         return () => {}; // No-op for unsupported platforms
     },
-    screenShotBinary: function (rect) {
-        return _capturePageBinary(rect);
+    /**
+     * Captures a screenshot and returns the raw PNG bytes.
+     * @param {Object|HTMLElement|string} [rectOrNodeOrSelector] - Area to capture. Can be:
+     *   - A rect object `{x, y, width, height}` specifying pixel coordinates
+     *   - A DOM element whose bounding rect will be captured
+     *   - A jQuery selector string (must match exactly one element)
+     *   - Omit to capture the full page
+     * @returns {Promise<Uint8Array>} PNG image data
+     */
+    screenShotBinary: function (rectOrNodeOrSelector) {
+        return _capturePageBinary(rectOrNodeOrSelector);
     },
-    screenShotToBlob: async function (rect) {
-        const bytes = await _capturePageBinary(rect);
+    /**
+     * Captures a screenshot and returns it as a PNG Blob.
+     * @param {Object|HTMLElement|string} [rectOrNodeOrSelector] - Area to capture. Can be:
+     *   - A rect object `{x, y, width, height}` specifying pixel coordinates
+     *   - A DOM element whose bounding rect will be captured
+     *   - A jQuery selector string (must match exactly one element)
+     *   - Omit to capture the full page
+     * @returns {Promise<Blob>} PNG Blob with type "image/png"
+     */
+    screenShotToBlob: async function (rectOrNodeOrSelector) {
+        const bytes = await _capturePageBinary(rectOrNodeOrSelector);
         return new Blob([bytes], { type: "image/png" });
     },
-    screenShotToPNGFile: async function (filePathToSave, rect) {
+    /**
+     * Captures a screenshot and writes it to a PNG file.
+     * @param {string} filePathToSave - VFS path to save the PNG file to
+     * @param {Object|HTMLElement|string} [rectOrNodeOrSelector] - Area to capture. Can be:
+     *   - A rect object `{x, y, width, height}` specifying pixel coordinates
+     *   - A DOM element whose bounding rect will be captured
+     *   - A jQuery selector string (must match exactly one element)
+     *   - Omit to capture the full page
+     * @returns {Promise<void>}
+     */
+    screenShotToPNGFile: async function (filePathToSave, rectOrNodeOrSelector) {
         if (!filePathToSave || typeof filePathToSave !== 'string') {
             throw new Error("filePathToSave must be a non-empty string");
         }
-        const bytes = await _capturePageBinary(rect);
+        const bytes = await _capturePageBinary(rectOrNodeOrSelector);
         return new Promise((resolve, reject) => {
             fs.writeFile(filePathToSave, bytes.buffer, 'binary', (err) => {
                 if (err) {

test/spec/Native-platform-test.js

@@ -461,6 +461,54 @@ define(function (require, exports, module) {
                         Phoenix.app.screenShotBinary({x: 0, y: 0, width: 100, height: 999999})
                     ).toBeRejectedWithError("rect y + height exceeds window innerHeight");
                 });
+
+                it("Should capture a screenshot of a DOM element", async function () {
+                    const el = document.createElement("div");
+                    el.id = "screenshot-test-element";
+                    el.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;background:red;";
+                    document.body.appendChild(el);
+                    try {
+                        const bytes = await Phoenix.app.screenShotBinary(el);
+                        expect(bytes instanceof Uint8Array).toBeTrue();
+                        expect(bytes.length).toBeGreaterThan(0);
+                        expect(isPNG(bytes)).withContext("Result should be valid PNG data").toBeTrue();
+                    } finally {
+                        el.remove();
+                    }
+                });
+
+                it("Should capture a screenshot using a jQuery selector string", async function () {
+                    const el = document.createElement("div");
+                    el.id = "screenshot-test-element";
+                    el.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;background:red;";
+                    document.body.appendChild(el);
+                    try {
+                        const bytes = await Phoenix.app.screenShotBinary("#screenshot-test-element");
+                        expect(bytes instanceof Uint8Array).toBeTrue();
+                        expect(bytes.length).toBeGreaterThan(0);
+                        expect(isPNG(bytes)).withContext("Result should be valid PNG data").toBeTrue();
+                    } finally {
+                        el.remove();
+                    }
+                });
+
+                it("Should throw when jQuery selector matches no elements", async function () {
+                    await expectAsync(
+                        Phoenix.app.screenShotBinary("#nonexistent-element-xyz")
+                    ).toBeRejectedWithError("No element found for selector: #nonexistent-element-xyz");
+                });
+
+                it("Should throw when jQuery selector matches multiple elements", async function () {
+                    await expectAsync(
+                        Phoenix.app.screenShotBinary("div")
+                    ).toBeRejectedWithError(/Selector must match exactly one element, but matched \d+: div/);
+                });
+
+                it("Should throw for invalid argument type", async function () {
+                    await expectAsync(
+                        Phoenix.app.screenShotBinary(42)
+                    ).toBeRejectedWithError("Expected a rect object, DOM node, or jQuery selector string");
+                });
             });
 
             describe("screenShotToBlob", function () {
@@ -477,6 +525,36 @@ define(function (require, exports, module) {
                     expect(blob.type).toEqual("image/png");
                     expect(blob.size).toBeGreaterThan(0);
                 });
+
+                it("Should return a Blob when given a DOM element", async function () {
+                    const el = document.createElement("div");
+                    el.id = "screenshot-blob-test-element";
+                    el.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;background:red;";
+                    document.body.appendChild(el);
+                    try {
+                        const blob = await Phoenix.app.screenShotToBlob(el);
+                        expect(blob instanceof Blob).toBeTrue();
+                        expect(blob.type).toEqual("image/png");
+                        expect(blob.size).toBeGreaterThan(0);
+                    } finally {
+                        el.remove();
+                    }
+                });
+
+                it("Should return a Blob when given a jQuery selector", async function () {
+                    const el = document.createElement("div");
+                    el.id = "screenshot-blob-test-element";
+                    el.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;background:red;";
+                    document.body.appendChild(el);
+                    try {
+                        const blob = await Phoenix.app.screenShotToBlob("#screenshot-blob-test-element");
+                        expect(blob instanceof Blob).toBeTrue();
+                        expect(blob.type).toEqual("image/png");
+                        expect(blob.size).toBeGreaterThan(0);
+                    } finally {
+                        el.remove();
+                    }
+                });
             });
 
             describe("screenShotToPNGFile", function () {
@@ -526,6 +604,29 @@ define(function (require, exports, module) {
                     expect(isPNG(bytes)).withContext("Written file should be valid PNG").toBeTrue();
                 });
 
+                it("Should write a valid PNG file when given a jQuery selector", async function () {
+                    const el = document.createElement("div");
+                    el.id = "screenshot-file-test-element";
+                    el.style.cssText = "position:fixed;top:0;left:0;width:100px;height:100px;background:red;";
+                    document.body.appendChild(el);
+                    try {
+                        await Phoenix.app.screenShotToPNGFile(testFilePath, "#screenshot-file-test-element");
+                        const content = await new Promise((resolve, reject) => {
+                            fs.readFile(testFilePath, 'binary', (err, data) => {
+                                if (err) {
+                                    reject(err);
+                                } else {
+                                    resolve(data);
+                                }
+                            });
+                        });
+                        const bytes = new Uint8Array(content);
+                        expect(isPNG(bytes)).withContext("Written file should be valid PNG").toBeTrue();
+                    } finally {
+                        el.remove();
+                    }
+                });
+
                 it("Should throw when filePathToSave is not provided", async function () {
                     await expectAsync(
                         Phoenix.app.screenShotToPNGFile()