fix: final review wave — CI checksum on cache hits, workflow permissions, docs corrections, scroll-into-view clicks

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DavertMik

.github/workflows/obscura.yml

@@ -12,6 +12,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 env:
   CI: true
   FORCE_COLOR: 1
@@ -29,6 +32,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v6
         with:
@@ -38,19 +43,19 @@ jobs:
           php-version: 8.0
       - name: npm install
         run: npm i --force
-      - name: Cache Obscura binary
+      - name: Cache Obscura tarball
         uses: actions/cache@v4
         with:
-          path: ~/obscura-bin
+          path: ~/obscura-bin/obscura.tar.gz
           key: obscura-${{ env.OBSCURA_VERSION }}-x86_64-linux
       - name: Download Obscura
         run: |
-          if [ ! -f ~/obscura-bin/obscura ]; then
-            mkdir -p ~/obscura-bin
-            curl -sL -o /tmp/obscura.tar.gz https://github.com/h4ckf0r0day/obscura/releases/download/${OBSCURA_VERSION}/obscura-x86_64-linux.tar.gz
-            echo "${OBSCURA_SHA256}  /tmp/obscura.tar.gz" | sha256sum -c -
-            tar xzf /tmp/obscura.tar.gz -C ~/obscura-bin
+          mkdir -p ~/obscura-bin
+          if [ ! -f ~/obscura-bin/obscura.tar.gz ]; then
+            curl -sfL -o ~/obscura-bin/obscura.tar.gz https://github.com/h4ckf0r0day/obscura/releases/download/${OBSCURA_VERSION}/obscura-x86_64-linux.tar.gz
           fi
+          echo "${OBSCURA_SHA256}  $HOME/obscura-bin/obscura.tar.gz" | sha256sum -c -
+          tar xzf ~/obscura-bin/obscura.tar.gz -C ~/obscura-bin
           ~/obscura-bin/obscura --version
       - name: start test server and obscura
         run: |

docs/alternative-browsers.md

@@ -61,7 +61,7 @@ headless Chromium.
 
 ## When to stay with Playwright
 
-- Anything visual: screenshots, visual regression, PDF (Obscura cannot; Kitesurf can).
+- Anything visual: screenshots, visual regression, PDF (neither helper exposes PDF output).
 - Visibility semantics: on Obscura every element reports as visible — `seeElement`/`dontSeeElement`
   throw and point you to `seeElementInDOM`.
 - Complex input: drag-and-drop, hover chains, file uploads, iframes, multi-tab, service workers.

docs/helpers/CDPBrowser.md

@@ -267,7 +267,7 @@ I.checkOption('agree', '//form');
 #### Parameters
 
 *   `field` **([string][1] | [object][3])** checkbox located by label | name | CSS | XPath | strict locator.
-*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element located by CSS | XPath | strict locator (currently ignored by this helper). 
 
 Returns **[Promise][4]<void>**&#x20;
 
@@ -332,7 +332,7 @@ I.click({css: 'nav a.login'});
 #### Parameters
 
 *   `locator` **([string][1] | [object][3])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element to search in CSS|XPath|Strict locator. 
+*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element to search in CSS|XPath|Strict locator (currently ignored by this helper). 
 
 <!---->
 
@@ -481,7 +481,7 @@ I.forceClick({css: 'nav a.login'});
 #### Parameters
 
 *   `locator` **([string][1] | [object][3])** clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element to search in CSS|XPath|Strict locator. 
+*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element to search in CSS|XPath|Strict locator (currently ignored by this helper). 
 
 Returns **[Promise][4]<void>**&#x20;
 
@@ -847,7 +847,7 @@ I.uncheckOption('agree', '//form');
 #### Parameters
 
 *   `field` **([string][1] | [object][3])** checkbox located by label | name | CSS | XPath | strict locator.
-*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element located by CSS | XPath | strict locator. 
+*   `context` **([string][1]? | [object][3])** (optional, `null` by default) element located by CSS | XPath | strict locator (currently ignored by this helper). 
 
 Returns **[Promise][4]<void>**&#x20;
 

docs/helpers/Obscura.md

@@ -99,6 +99,8 @@ Type: [object][2]
 }
 ```
 
+## Methods
+
 ### Parameters
 
 *   `config` **ObscuraConfig** 

lib/helper/CDPBrowser.js

@@ -801,7 +801,7 @@ class CDPBrowser extends Helper {
    * ```
    *
    * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator (currently ignored by this helper).
    * @returns {Promise<void>}
    * @throws {Error} if the matched element has a zero-size bounding box.
    */
@@ -844,7 +844,7 @@ class CDPBrowser extends Helper {
    * ```
    *
    * @param {CodeceptJS.LocatorOrString} locator clickable link or button located by text, or any element located by CSS|XPath|strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element to search in CSS|XPath|Strict locator (currently ignored by this helper).
    * @returns {Promise<void>}
    */
   async forceClick(locator, context = null) {
@@ -959,7 +959,7 @@ class CDPBrowser extends Helper {
    * ```
    *
    * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator (currently ignored by this helper).
    * @returns {Promise<void>}
    */
   async checkOption(field, context = null) {
@@ -978,7 +978,7 @@ class CDPBrowser extends Helper {
    * ```
    *
    * @param {CodeceptJS.LocatorOrString} field checkbox located by label | name | CSS | XPath | strict locator.
-   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
+   * @param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator (currently ignored by this helper).
    * @returns {Promise<void>}
    */
   async uncheckOption(field, context = null) {

lib/helper/Obscura.js

@@ -89,6 +89,8 @@ const config = {}
  *   }
  * }
  * ```
+ *
+ * ## Methods
  */
 class Obscura extends CDPBrowser {
   /**

lib/helper/clientscripts/cdpBrowserClient.js

@@ -29,6 +29,7 @@ export default function installCodeceptClient() {
     attrs: (els, p) => els.map(el => el.getAttribute(p.name)),
     html: els => els.map(el => el.outerHTML),
     rect: els => {
+      if (els[0].scrollIntoView) els[0].scrollIntoView({ block: 'center', inline: 'center' })
       const r = els[0].getBoundingClientRect()
       return { x: r.x, y: r.y, width: r.width, height: r.height }
     },