feat(types): execInPage, onRequest & party APIs + supports() capability helper (#10933)

* feat(types): add execInPage and onRequest APIs to Presence/iFrame

* docs(types): document feature-detection for execInPage/onRequest on older extensions

* feat(premid): add supports() helper for version-safe capability detection

* feat(lint): error on unguarded execInPage/onRequest with autofix to wrap in supports() check

* feat(types): add party to PresenceData (2.14.0)

* fix(types): infer execInPage arg types into the page closure

Type execInPage's rest args as a tuple generic (A extends unknown[]) so
the values passed are forwarded to the closure with their types instead
of erasing to unknown[]. Applies to both Presence and iFrame overloads.

Addresses review feedback on #10933.

* docs: document execInPage, onRequest and the party object

- presence-class (API + guide): detailed execInPage (function + declarative
  ExecInPageSpec forms) and onRequest (RequestFilter, InterceptedRequest,
  unsubscribe), both gated behind the supports() helper.
- presence-data: party / PartyData (only honored on ActivityType.Playing).
- utility-functions: supports() capability-detection helper.
- iframe: execInPage reference.

For #10933.

* docs: note dot-path support for execInPage pick/omit

pick/omit accept dot-paths in the runtime (PreMiD/Extension#780); document
the nested-field capability on the type and in the API reference.

* style: realign execInPage spec table

Author: Timeraa

.gitignore

@@ -3,6 +3,7 @@
 !cli/bin/**/*.*js
 !*.config.*js
 !.github/scripts/**/*.mjs
+!eslint-rules/**/*.mjs
 websites/**/dist
 websites/**/tsconfig.json
 node_modules

@types/premid/index.d.ts

@@ -150,6 +150,18 @@ declare global {
      * @since 2.8.0
      */
     smallImageUrl?: string
+    /**
+     * Party info shown on Playing activities (e.g. "2 of 5").
+     *
+     * Only honored on `type: ActivityType.Playing`. `partyId` is optional —
+     * when omitted a stable fallback is generated.
+     * @since 2.14.0
+     */
+    party?: {
+      partyId?: string
+      partySize: number
+      maxPartySize: number
+    }
   }
 
   interface MediaPresenceData extends BasePresenceData {
@@ -429,6 +441,56 @@ declare global {
     content: T
   }
 
+  /**
+   * Declarative, CSP-immune form of `Presence#execInPage` / `iFrame#execInPage`.
+   * Use instead of a closure when you only need to read a value or call a page
+   * function — it works even on pages whose CSP blocks `eval`.
+   * @since 2.14
+   */
+  interface ExecInPageSpec {
+    /** Dot-path to a value on `window` to read, e.g. `'player.track.name'`. */
+    get?: string
+    /** Dot-path to a page function to invoke, e.g. `'spotifyPlayer.getState'`. */
+    call?: string
+    /** Arguments passed to the `call` function (must be serializable). */
+    args?: unknown[]
+    /** Keep only these keys of the result. Dot-paths allowed, e.g. `'track.name'`. */
+    pick?: string[]
+    /** Drop these keys from the result. Dot-paths allowed, e.g. `'track.art'`. */
+    omit?: string[]
+  }
+
+  /**
+   * Filter for `Presence#onRequest`.
+   * @since 2.14
+   */
+  interface RequestFilter {
+    /** Match the request URL — substring (string) or pattern (RegExp). */
+    url?: string | RegExp
+    /** Match the HTTP method (case-insensitive). One or many. */
+    method?: string | string[]
+  }
+
+  /**
+   * Read-only snapshot of a captured request/response passed to an
+   * `Presence#onRequest` callback.
+   * @since 2.14
+   */
+  interface InterceptedRequest {
+    url: string
+    method: string
+    requestHeaders: Record<string, string>
+    requestBody: string | null
+    status: number
+    statusText: string
+    ok: boolean
+    responseHeaders: Record<string, string>
+    responseBody: string | null
+    /** URL of the frame the request originated from (page or iframe). */
+    frameUrl: string
+    timestamp: number
+  }
+
   /**
    * Useful tools for developing presences
    * @link https://docs.premid.app/en/dev/presence/class
@@ -662,6 +724,74 @@ declare global {
     getPageVariable<T extends Record<string, any> = Record<string, unknown>>(
       ...variables: string[]
     ): Promise<T>
+    /**
+     * Run code in the web page's own realm and get its (serializable) return value.
+     *
+     * Unlike `getPageVariable`, the function executes *inside the page*, so you
+     * can call the page's own functions and reshape the result — stripping
+     * non-serializable parts (streams, DOM nodes, circular refs) — before it is
+     * sent back. The return value must be JSON-serializable.
+     *
+     * The closure cannot reference activity-side variables; pass them as args.
+     * @example
+     * const track = await presence.execInPage((id) => {
+     *   const s = window.spotifyPlayer.getCurrentState()
+     *   return { id, title: s.track.name, paused: s.paused }
+     * }, userId)
+     * @remarks
+     * Added in extension 2.14. Older versions lack this method, so feature-detect
+     * with the bundled `supports` helper before calling:
+     * ```ts
+     * import { supports } from 'premid'
+     * if (supports(presence, 'execInPage')) {
+     *   const data = await presence.execInPage(() => window.appState)
+     * }
+     * ```
+     * @since 2.14
+     */
+    execInPage<T = unknown, A extends unknown[] = unknown[]>(
+      fn: (...args: A) => T | Promise<T>,
+      ...args: A
+    ): Promise<T>
+    /**
+     * Declarative, CSP-immune variant of `execInPage`. Reads a value (`get`) or
+     * calls a page function (`call`) and optionally strips fields — works even
+     * on pages whose CSP blocks `eval`.
+     * @example
+     * const paused = await presence.execInPage({ call: 'spotifyPlayer.isPaused' })
+     * @since 2.14
+     */
+    execInPage<T = unknown>(spec: ExecInPageSpec): Promise<T>
+    /**
+     * Read (never modify) requests the page makes via `fetch` or
+     * `XMLHttpRequest`, including requests made inside the activity's iframes.
+     * The callback receives a read-only snapshot of the request and its response.
+     *
+     * Interception runs from `document_start`; requests that complete before the
+     * activity registers a filter are replayed with request metadata only (no
+     * response body).
+     * @param filter Match by URL (substring or RegExp) and/or HTTP method.
+     * @param callback Invoked with each matching request.
+     * @returns Unsubscribe function.
+     * @example
+     * presence.onRequest({ url: '/api/now-playing', method: 'GET' }, (req) => {
+     *   const data = JSON.parse(req.responseBody ?? '{}')
+     * })
+     * @remarks
+     * Added in extension 2.14. Older versions lack this method, so feature-detect
+     * with the bundled `supports` helper before calling:
+     * ```ts
+     * import { supports } from 'premid'
+     * if (supports(presence, 'onRequest')) {
+     *   presence.onRequest({ url: '/api/now-playing' }, (req) => { ... })
+     * }
+     * ```
+     * @since 2.14
+     */
+    onRequest(
+      filter: RequestFilter,
+      callback: (request: InterceptedRequest) => void
+    ): () => void
     /**
      * Sends data back to application
      * @param event Event
@@ -789,6 +919,20 @@ declare global {
      * @since 2.0-BETA3
      */
     getUrl(): Promise<string>
+    /**
+     * Run code in the iframe page's own realm and get its (serializable) return
+     * value. See `Presence#execInPage` for the full contract.
+     * @remarks
+     * Added in extension 2.14 — feature-detect with the bundled `supports`
+     * helper (`supports(iframe, 'execInPage')`) before calling so older
+     * extensions don't throw.
+     * @since 2.14
+     */
+    execInPage<T = unknown, A extends unknown[] = unknown[]>(
+      fn: (...args: A) => T | Promise<T>,
+      ...args: A
+    ): Promise<T>
+    execInPage<T = unknown>(spec: ExecInPageSpec): Promise<T>
     /**
      * Subscribe to events emitted by the extension
      * @param eventName

docs/v1/api/iframe.md

@@ -62,6 +62,31 @@ const url = await iframe.getUrl()
 console.log(url) // "https://example.com/embed/video"
 ```
 
+### execInPage
+
+::: tip Requires extension 2.14+
+Added in extension **2.14**. Guard the call with the bundled [`supports`](/v1/api/utility-functions#supports) helper (`supports(iframe, 'execInPage')`) so it degrades gracefully on older extensions.
+:::
+
+<!-- eslint-skip -->
+
+```typescript
+execInPage<T = unknown, A extends unknown[] = unknown[]>(fn: (...args: A) => T | Promise<T>, ...args: A): Promise<T>;
+execInPage<T = unknown>(spec: ExecInPageSpec): Promise<T>;
+```
+
+Runs code in the iframe page's own realm and resolves with its (serializable) return value. Behaves exactly like [`Presence#execInPage`](/v1/api/presence-class#execinpage) — see there for the full contract, the declarative `ExecInPageSpec` form, and examples.
+
+#### Example
+
+```typescript
+import { supports } from 'premid'
+
+if (supports(iframe, 'execInPage')) {
+  const duration = await iframe.execInPage(() => window.player.getDuration())
+}
+```
+
 ### on
 
 <!-- eslint-skip -->

docs/v1/api/presence-class.md

@@ -124,6 +124,153 @@ const {
 )
 ```
 
+### execInPage
+
+::: tip Requires extension 2.14+
+`execInPage` was added in extension **2.14**. Activities run on every installed version, so guard the call with the bundled [`supports`](/v1/api/utility-functions#supports) helper — on older extensions the method is missing, and feature-detecting lets it degrade gracefully instead of throwing.
+:::
+
+<!-- eslint-skip -->
+
+```typescript
+execInPage<T = unknown, A extends unknown[] = unknown[]>(fn: (...args: A) => T | Promise<T>, ...args: A): Promise<T>;
+execInPage<T = unknown>(spec: ExecInPageSpec): Promise<T>;
+```
+
+Runs code in the **web page's own realm** and resolves with its return value. Unlike [`getPageVariable`](#getpagevariable), which only reads a variable, `execInPage` runs a function _inside the page_ — so you can call the page's own functions and reshape the result before it is sent back to the activity.
+
+The return value must be **JSON-serializable**. Strip non-serializable parts (DOM nodes, streams, circular references) inside the function before returning.
+
+::: warning The closure is isolated
+The function is serialized and re-evaluated in the page, so it **cannot reference activity-side variables** (imports, closures, module scope). Pass any values it needs as trailing arguments — they are forwarded to the function with their types preserved.
+:::
+
+#### Function form
+
+##### Parameters
+
+- `fn`: A function executed in the page. Receives `...args` and returns a serializable value (or a promise of one).
+- `args`: Serializable values forwarded to `fn` as arguments.
+
+##### Example
+
+```typescript
+import { supports } from 'premid'
+
+if (supports(presence, 'execInPage')) {
+  const track = await presence.execInPage((userId) => {
+    const state = window.spotifyPlayer.getCurrentState()
+    return { userId, title: state.track.name, paused: state.paused }
+  }, currentUserId)
+}
+```
+
+#### Declarative form (`ExecInPageSpec`)
+
+For pages whose Content-Security-Policy blocks `eval`, pass a declarative spec instead of a closure. It reads a value or calls a page function by dot-path — no code evaluation, so it works under strict CSP.
+
+| Property | Type        | Description                                                                  |
+| -------- | ----------- | ---------------------------------------------------------------------------- |
+| `get`    | `string`    | Dot-path to a value on `window` to read (e.g. `'player.track.name'`).        |
+| `call`   | `string`    | Dot-path to a page function to invoke (e.g. `'spotifyPlayer.getState'`).     |
+| `args`   | `unknown[]` | Arguments passed to the `call` function (must be serializable).              |
+| `pick`   | `string[]`  | Keep only these keys of the result. Dot-paths allowed (e.g. `'track.name'`). |
+| `omit`   | `string[]`  | Drop these keys from the result. Dot-paths allowed (e.g. `'track.art'`).     |
+
+##### Example
+
+```typescript
+// Read a nested value
+const title = await presence.execInPage<string>({ get: 'player.track.name' })
+
+// Call a page function and keep only some fields of the result
+const state = await presence.execInPage({
+  call: 'spotifyPlayer.getState',
+  pick: ['paused', 'position'],
+})
+
+// Dot-paths pull nested fields out of a call result
+const track = await presence.execInPage({
+  call: 'spotifyPlayer.getState',
+  pick: ['track.name', 'track.artist'],
+}) // → { track: { name, artist } }
+```
+
+### onRequest
+
+::: tip Requires extension 2.14+
+`onRequest` was added in extension **2.14**. Guard the call with the bundled [`supports`](/v1/api/utility-functions#supports) helper so it degrades gracefully on older extensions.
+:::
+
+<!-- eslint-skip -->
+
+```typescript
+onRequest(filter: RequestFilter, callback: (request: InterceptedRequest) => void): () => void;
+```
+
+**Reads** (never modifies) requests the page makes via `fetch` or `XMLHttpRequest`, including requests made inside the activity's iframes. Use it to pull data straight from a site's own API responses instead of scraping the DOM.
+
+Interception runs from `document_start`. Requests that complete **before** your activity registers a filter are replayed to the callback with request metadata only — no `responseBody`.
+
+#### Parameters
+
+- `filter` (`RequestFilter`): Which requests to match. Omitting a field matches everything for that field.
+
+  | Property | Type                 | Description                                                     |
+  | -------- | -------------------- | --------------------------------------------------------------- |
+  | `url`    | `string \| RegExp`   | Match the request URL — substring (string) or pattern (RegExp). |
+  | `method` | `string \| string[]` | Match the HTTP method (case-insensitive). One or many.          |
+
+- `callback`: Invoked with an `InterceptedRequest` for each matching request.
+
+#### Returns
+
+An **unsubscribe** function. Call it to stop receiving requests (e.g. when the relevant page section is gone).
+
+#### InterceptedRequest
+
+A read-only snapshot of the request and its response passed to the callback:
+
+| Property          | Type                     | Description                                               |
+| ----------------- | ------------------------ | --------------------------------------------------------- |
+| `url`             | `string`                 | Request URL                                               |
+| `method`          | `string`                 | HTTP method                                               |
+| `requestHeaders`  | `Record<string, string>` | Request headers                                           |
+| `requestBody`     | `string \| null`         | Request body, if any                                      |
+| `status`          | `number`                 | Response status code                                      |
+| `statusText`      | `string`                 | Response status text                                      |
+| `ok`              | `boolean`                | `true` for 2xx responses                                  |
+| `responseHeaders` | `Record<string, string>` | Response headers                                          |
+| `responseBody`    | `string \| null`         | Response body (`null` for requests replayed at page load) |
+| `frameUrl`        | `string`                 | URL of the frame the request originated from              |
+| `timestamp`       | `number`                 | When the request completed (Unix ms)                      |
+
+#### Example
+
+```typescript
+import { supports } from 'premid'
+
+if (supports(presence, 'onRequest')) {
+  const unsubscribe = presence.onRequest(
+    { url: '/youtubei/v1/player', method: 'POST' },
+    (request) => {
+      if (!request.responseBody)
+        return
+
+      const { videoDetails } = JSON.parse(request.responseBody)
+      // videoDetails.title, videoDetails.author, videoDetails.lengthSeconds, ...
+    },
+  )
+
+  // Later, to stop listening:
+  // unsubscribe()
+}
+```
+
+::: warning Read-only
+`onRequest` can only observe requests — it cannot modify, block, or replay them. It is intended for reading data the page already fetches, not for making your own requests.
+:::
+
 ### getSetting
 
 <!-- eslint-skip -->