{/* This file is NOT rendered directly. Sections are imported by framework pages. */}

<section id="intro">
  The network blocker intercepts outgoing `fetch` and `XMLHttpRequest` calls and blocks them based on consent state and domain rules. This catches tracking requests that happen outside of script loading - for example, beacon calls, API requests to analytics endpoints, or pixel fires from already-loaded scripts.
</section>

<section id="reference">
  ## Rule Matching

  Rules match requests using three criteria:

  ### Domain matching

  The `domain` field matches the request hostname. Subdomains are automatically included - a rule for `google-analytics.com` also matches `www.google-analytics.com` and `stats.google-analytics.com`.

  ### Path matching

  The optional `pathIncludes` field requires the request URL path to contain the specified substring. This lets you target specific endpoints without blocking the entire domain.

  ### Method matching

  The optional `methods` array restricts the rule to specific HTTP methods. If omitted, the rule applies to all methods.

  ## Consent Conditions

  Like the script loader, `category` accepts a `HasCondition`:

  ```tsx
  // Simple
  { category: 'measurement' }

  // Must have both
  { category: { and: ['measurement', 'marketing'] } }

  // Must have either
  { category: { or: ['measurement', 'marketing'] } }
  ```

  ## Monitoring Blocked Requests

  ### Console logging

  Blocked requests are logged to the console by default. Disable with `logBlockedRequests: false`.

  ### Callback

  Use `onRequestBlocked` to handle blocked requests programmatically:

  ```tsx
  networkBlocker: {
    rules: [...],
    onRequestBlocked: ({ method, url, rule }) => {
      console.log(`Blocked ${method} ${url} (rule: ${rule?.id})`);
    },
  }
  ```
</section>

<section id="api-reference">
  ## API Reference

  | Property     | Type                           | Description                                                                                                                                 | Default |  Required  |
  | :----------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :------ | :--------: |
  | id           | string \| undefined            | Optional identifier for the rule.&#xA;Useful for debugging and logging.                                                                     | -       |  Optional  |
  | domain       | string                         | Domain that this rule applies to.                                                                                                           | -       | ✅ Required |
  | pathIncludes | string \| undefined            | Optional path substring that must be present in the request path&#xA;for the rule to apply.                                                 | -       |  Optional  |
  | methods      | string\[] \| undefined         | Optional list of HTTP methods that this rule applies to.&#xA;If omitted, the rule applies to all methods.                                   | -       |  Optional  |
  | category     | HasCondition\<AllConsentNames> | Consent condition that must be satisfied to allow the request.&#xA;When this condition is not satisfied, matching requests will be blocked. | -       | ✅ Required |

  | Property           | Type                                              | Description                                                           | Default |  Required  |
  | :----------------- | :------------------------------------------------ | :-------------------------------------------------------------------- | :------ | :--------: |
  | enabled            | boolean \| undefined                              | Whether the network blocker is enabled.                               | -       |  Optional  |
  | initialConsents    | ConsentState \| undefined                         | The consent state snapshot that is currently used for blocking logic. | -       |  Optional  |
  | logBlockedRequests | boolean \| undefined                              | Whether to automatically log blocked requests to the console.         | -       |  Optional  |
  | onRequestBlocked   | ((info: BlockedRequestInfo) => void) \| undefined | Callback invoked whenever a request is blocked.                       | -       |  Optional  |
  | rules              | NetworkBlockerRule\[]                             | Domain rules that determine which requests should be blocked.         | -       | ✅ Required |
</section>