Document page and visitor context in webframes

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,42 @@ 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:
+
+```js
+window.parent.postMessage({
+    action: {
+        action: '@webframe.navigate',
+        path: 'guides/getting-started',
+    },
+}, '*');
+```
+
+The path is always resolved within the current site, so navigation stays inside it.
+
 ## Webframes and actions
 
 Webframes are powerful elements to integrate in GitBook external applications or complete UI. Passing data to the webframe can be done using the `data` prop. But the webframe also needs to be able to communicate data back to the top component. It can be achieved using the `window.postMessage`:

docs/integrations/development/contentkit/reference.md

@@ -264,6 +264,8 @@ 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, 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 by posting a `@webframe.navigate` action. See [Interactivity](../../contentkit/interactivity.md#page-and-visitor-context).
+
 #### `select`
 
 ```tsx

docs/integrations/guides/interactivity.md

@@ -95,6 +95,42 @@ 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:
+
+```js
+window.parent.postMessage({
+    action: {
+        action: '@webframe.navigate',
+        path: 'guides/getting-started',
+    },
+}, '*');
+```
+
+The path is always resolved within the current site, so navigation stays inside it.
+
 ### Editable blocks
 
 Some blocks might be static or only generated from link unfurling, but most blocks are designed to be editable by the user. Editable means that the user can interact with the blocks to change its properties.