Document webframe page and visitor context

docs/integrations/configurations.md

@@ -98,6 +98,7 @@ The scopes your integration has permissions for.
     - site:script:inject ## Internal scope - see note below
     - site:script:cookies ## Internal scope - see note below
     - site:visitor:auth ## Enable workflows related to authenticated access
+    - site:visitor:claims ## Expose visitor claims to webframes
     - site:adaptive:read ## Read claims available from Adaptive Content
     - site:adaptive:write ## Write claims avaiable to Adaptive Content
     # OpenAPI

docs/integrations/contentkit/interactivity.md

@@ -91,6 +91,27 @@ window.addEventListener("message", (event) => {
 });
 ```
 
+## Page and visitor context
+
+GitBook injects contextual information about the current site into the webframe `state`, alongside the values you bind through the `data` prop:
+
+- `state.page` — the current page as `{ id, path, title }`. Always available.
+- `state.visitor` — the visitor claims, when the integration has the `site:visitor:claims` [scope](../configurations.md#scopes).
+
+This context is delivered client-side through the same `message` event as your bound `data`, so it does not change how the integration block is cached:
+
+```js
+window.addEventListener("message", (event) => {
+    const state = event.data?.state;
+    if (!state) return;
+
+    if (state.page) {
+        const { id, path, title } = state.page;
+        // e.g. build a link to a sibling page from `path`
+    }
+});
+```
+
 ## Navigating to another page
 
 A webframe can navigate the reader to another page in the site by posting a `@webframe.navigate` action. The `path` is resolved relative to the site root (the part after your site's base URL), so it can point to a page in any section or space of the site, and navigation always stays within it. You can also pass an optional `anchor` to scroll to a heading within the target page:

docs/integrations/development/contentkit/reference.md

@@ -264,7 +264,7 @@ If you need a copy button, only add it when your integration has a supported way
 | `buttons`       | `Array<Button>`          | Overlay buttons          |
 | `data`          | `Record<string, string>` | State dependencies       |
 
-The `data` values reach the frame through the `message` event as `event.data.state`. A webframe can also navigate the reader to another page in the site by posting a `@webframe.navigate` action with a `path`. See [Interactivity](../../contentkit/interactivity.md#navigating-to-another-page).
+The `data` values, together with GitBook-provided context, reach the frame through the `message` event as `event.data.state`. GitBook reserves two keys in `state`: `page` (`{ id, path, title }` of the current page, always available) and `visitor` (visitor claims, with the `site:visitor:claims` scope). A webframe can also navigate the reader to another page in the site by posting a `@webframe.navigate` action with a `path`. See [Interactivity](../../contentkit/interactivity.md#page-and-visitor-context).
 
 #### `select`
 

docs/integrations/guides/interactivity.md

@@ -95,6 +95,27 @@ window.addEventListener("message", (event) => {
 });
 ```
 
+### Page and visitor context
+
+GitBook injects contextual information about the current site into the webframe `state`, alongside the values you bind through the `data` prop:
+
+- `state.page` — the current page as `{ id, path, title }`. Always available.
+- `state.visitor` — the visitor claims, when the integration has the `site:visitor:claims` [scope](../configurations.md#scopes).
+
+This context is delivered client-side through the same `message` event as your bound `data`, so it does not change how the integration block is cached:
+
+```js
+window.addEventListener("message", (event) => {
+    const state = event.data?.state;
+    if (!state) return;
+
+    if (state.page) {
+        const { id, path, title } = state.page;
+        // e.g. build a link to a sibling page from `path`
+    }
+});
+```
+
 ### Navigating to another page
 
 A webframe can navigate the reader to another page in the site by posting a `@webframe.navigate` action. The `path` is resolved relative to the site root (the part after your site's base URL), so it can point to a page in any section or space of the site, and navigation always stays within it. You can also pass an optional `anchor` to scroll to a heading within the target page: