docs: hybrid headers, context and browser extension more in depth (#50)

* chore: update and pin dependencies
* docs: add a separate page for the browser extension
* docs: excludeBy option in register

.npmrc

@@ -1 +1,2 @@
 package-lock=false
+save-exact=true

docs/guides/browser-extension.md

@@ -0,0 +1,34 @@
+---
+title: Browser extension
+---
+
+Developing layouts and podlets mostly works the same way as other web servers. Still, there are a couple of scenarios where the built-in developer tools in your browser can fall a bit short. The Podium Developer Tools browser extension can help.
+
+## Download the browser extension
+
+The Podium browser extension is available for Firefox and Chromium-based browsers.
+
+- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/podium-developer-tools/)
+- [Chromium](https://chromewebstore.google.com/detail/podium-development-extens/jdlcejoeifgnnnckhnhapbmgieajaipl) based browsers
+
+## Using the browser extension
+
+First, you may have to allow the extension to run on the page you're debugging. In Firefox this is shown with a mark by the extensions drawer, and on the extension itself.
+
+![](/img/browser-extension-permissions.png)
+
+The extension adds two new panes to your browser's developer tools that cover two main use-cases. You may have to open an overflow menu to see them.
+
+![](/img/browser-extension-devtools-panes.png)
+
+### The Podium Context pane
+
+This pane is used when developing podlets to change the default values set on the [Podium context](/docs/guides/context). Say you want to test how your podlet behaves when given a different `deviceType` value. You could make changes in code, restart the server and then do your test, or you can use the extension and it's [partner middleware](https://github.com/podium-lib/dev-tool/tree/main/packages/server) to quickly swap values at runtime.
+
+### The Podium Headers pane
+
+This pane helps you set HTTP headers on requests to the server. It's mainly designed for use with Podium layouts, but can be used to set any header for any server. It comes with presets for [hybrid HTTP headers](/docs/guides/hybrid#hybrid-http-headers), but you can add and remove any headers you might need.
+
+## Missing a feature?
+
+If you have ideas for additional features that would help you develop and debug Podium applications, please [open an issue in the dev-tool repo](https://github.com/podium-lib/dev-tool/issues). If an issue allready exists, give it a thumbs-up.

docs/guides/context.md

@@ -125,6 +125,12 @@ podlet.defaults({
 });
 ```
 
+:::tip
+
+Get the [browser extension](/docs/guides/browser-extension) and the accompanying [dev-tool middleware](https://github.com/podium-lib/dev-tool/tree/main/packages/server) to make it possible to change these defaults without changing code and restarting your server.
+
+:::
+
 [bcp47]: https://tools.ietf.org/html/bcp47
 [kebab case]: https://en.wikipedia.org/wiki/Kebab_case
 [camel case]: https://en.wikipedia.org/wiki/Camel_case

docs/guides/hybrid.md

@@ -14,19 +14,43 @@ Layouts and podlets need to be able to adapt to requests from a hybrid web view.
 
 ### Hybrid HTTP headers
 
+:::tip
+
+Get the [browser extension](/docs/guides/browser-extension) to make it easier to set the hybrid HTTP headers when developing locally.
+
+:::
+
 | Header                    | Example                        | Description                                                                               |
 | ------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------- |
 | `x-podium-app-id`         | `[email protected]`    | To identify clients in logs                                                               |
 | `x-podium-base-font-size` | `1rem`                         | To set base font size variable in CSS based on accessibility settings in the native host. |
 | `x-podium-device-type`    | `hybrid-ios`, `hybrid-android` | To give hints to the server what should be included in the response.                      |
-| `Authorization`           | `Bearer eyJhbGciOiJIU...`      | Optional. Signifies a logged-in user.                                                     |
 
-#### Podium developer tools extension
+### Podium context
+
+Requests that include the hybrid HTTP headers have their values added to the Podium context, in addition to the [default context variables](/docs/guides/context#default-context-variables).
+
+| Header                    | Context name   | Description                                                           |
+| ------------------------- | -------------- | --------------------------------------------------------------------- |
+| `x-podium-app-id`         | `appId`        |                                                                       |
+| `x-podium-base-font-size` | `baseFontSize` |                                                                       |
+| `x-podium-device-type`    | `deviceType`   | Overrides the value that would otherwise be derived from `User-Agent` |
 
-Get the extension to make it easier to set these HTTP headers when developing locally:
+### Conditionally fetch podlets
+
+In a hybrid web view setting your layout may want to exclude things like the header and footer. These are likely podlets, and Podium has an option when you register podlets to exclude them by device type.
+
+```js
+const headerPodlet = layout.client.register({
+  name: "header",
+  uri: "http://header/manifest.json",
+  excludeBy: {
+    deviceType: ["hybrid-ios", "hybrid-android"],
+  },
+});
+```
 
-- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/podium-developer-tools/)
-- [Chromium](https://chromewebstore.google.com/detail/podium-development-extens/jdlcejoeifgnnnckhnhapbmgieajaipl) based browsers
+In this case, if a request has the `x-podium-device-type: hybrid-ios` HTTP header, Podium will serve an empty response to the `headerPodlet.fetch()` call.
 
 ## Client-side communcication
 

docs/guides/podlet-development.md

@@ -99,6 +99,12 @@ podlet.defaults({
 });
 ```
 
+:::tip
+
+Get the [browser extension](/docs/guides/browser-extension) and the accompanying [dev-tool middleware](https://github.com/podium-lib/dev-tool/tree/main/packages/server) to make it possible to change these defaults without changing code and restarting your server.
+
+:::
+
 ### HTML pages and page fragments
 
 In production, your podlet's content route will be responding with an HTML fragment devoid of its wrapping `<html>` or `<body>` tags. However, in development you will want to wrap your fragment in a light HTML page, especially if your podlet makes use of client side assets such as JavaScript or CSS.

package.json

@@ -14,19 +14,19 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.3.2",
-    "@docusaurus/plugin-client-redirects": "^3.3.2",
-    "@docusaurus/preset-classic": "^3.3.2",
-    "@mdx-js/react": "^3.0.0",
-    "clsx": "^1.2.1",
+    "@docusaurus/core": "3.4.0",
+    "@docusaurus/plugin-client-redirects": "3.4.0",
+    "@docusaurus/preset-classic": "3.4.0",
+    "@mdx-js/react": "3.0.1",
+    "clsx": "2.1.1",
     "docusaurus-lunr-search": "3.5.0",
-    "prism-react-renderer": "^2.1.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "prism-react-renderer": "2.3.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.3.2",
-    "@docusaurus/types": "^3.3.2"
+    "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/types": "3.4.0"
   },
   "browserslist": {
     "production": [
@@ -41,6 +41,6 @@
     ]
   },
   "engines": {
-    "node": ">=18.0"
+    "node": ">=20.0"
   }
 }

sidebars.js

@@ -40,6 +40,7 @@ const sidebars = {
         { type: "doc", id: "guides/layout-development" },
         { type: "doc", id: "guides/podlet-development" },
         { type: "doc", id: "guides/hybrid" },
+        { type: "doc", id: "guides/browser-extension" },
       ],
     },
     {