@peax/consent-core 0.6.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,207 @@
+# @peax/consent-core
+
+[Peax Consent](../../README.md) · [Documentation](../../docs/README.md) · [React banner](../consent-banner-react/README.md)
+
+Framework-independent consent validation, decisions, and an in-memory runtime with immutable snapshots and subscriptions.
+
+> [!NOTE]
+> The root API evaluates and records decisions; opt-in enforcement subpaths control explicitly guarded operations. The React banner does not depend on it; connect the banner through your application's callbacks.
+
+## Create consent
+
+`createConsent(input)` is the only runtime export from the root entry. Explicit persistence is available separately through `/storage` and `/storage/localforage`; see [Consent storage](../../docs/consent-storage.md). Opt-in request enforcement is available through `/enforcement/fetch` and `/enforcement/axios`; see [Consent-controlled fetch](../../docs/consent-fetch.md) and [Consent-controlled Axios](../../docs/consent-axios.md). The consent factory validates decoded `{ currentAppPolicy, initialState }` data and returns `ValidationResult<ConsentRuntime>`: either `{ success: true, data }` or `{ success: false, issues }`. Both fields are required; malformed saved data is never replaced with an empty default.
+
+Opt-in external script/iframe loading is available through `/enforcement/script` and `/enforcement/iframe`; see [Consent-controlled scripts and iframes](../../docs/consent-dom.md). These loaders own only their explicitly created nodes. Removing a script cannot undo its execution or shut down its SDK.
+
+Additional subpaths provide [integration lifecycles and a narrowly scoped PostHog helper](../../docs/consent-integrations.md) (`/enforcement/integration`, `/enforcement/posthog`) plus [opt-in marked HTML](../../docs/consent-markup.md) (`/enforcement/markup`). These do not add root runtime exports. The separate [React consent bindings](../../docs/consent-react.md) depend on core; the published banner remains independent.
+
+```ts
+import { createConsent } from '@peax/consent-core'
+import type { ConsentPolicy } from '@peax/consent-core'
+
+const currentAppPolicy: ConsentPolicy = {
+  purposes: [{
+    id: 'product-usage-analysis',
+    title: 'Product usage analysis',
+    description: 'Measure application usage.',
+  }],
+  uses: [{
+    id: 'product-analytics',
+    serviceId: 'posthog',
+    categoryId: 'analytics',
+    purposeId: 'product-usage-analysis',
+    consentVersion: 1,
+  }],
+}
+
+const created = createConsent({ currentAppPolicy, initialState: { choices: [] } })
+if (!created.success) throw new Error(JSON.stringify(created.issues))
+const consent = created.data
+
+consent.evaluate('product-analytics')
+// { allowed: false, reason: 'undecided' }
+
+const unsubscribe = consent.subscribe(() => {
+  console.log(consent.getSnapshot(), consent.getMismatchedConsent())
+})
+
+// Capture the policy when showing the prompt, not when submitting it.
+const userConsentedPolicy = consent.getSnapshot().currentAppPolicy
+
+// Later, in response to an explicit applied user decision:
+const result = consent.setCategoryConsent({
+  userConsentedPolicy,
+  categoryId: 'analytics',
+  decision: 'granted',
+})
+if (!result.success) console.error(result.issues)
+
+consent.evaluate('product-analytics') // { allowed: true }
+unsubscribe()
+```
+
+| Method | Contract |
+| --- | --- |
+| `getSnapshot()` | Returns frozen `{ currentAppPolicy, state }`, retaining its identity until a committed change |
+| `evaluate(useId)` | Evaluates against the active policy and latest state |
+| `getMismatchedConsent()` | Returns cached, deeply frozen outstanding requirements in policy order |
+| `setConsentDecision({ userConsentedPolicy, useId, decision })` | Validates and applies a per-use decision to the latest state at the presented version |
+| `setCategoryConsent({ userConsentedPolicy, categoryId, decision })` | Validates and atomically applies all category choices from the presented policy |
+| `setConsentDecisions({ userConsentedPolicy, decisions })` | Validates disjoint category/use targets and publishes the complete batch once; [submission/persistence contract](../../docs/consent-decisions.md) |
+| `updatePolicy(input)` | Validates and replaces the active policy without changing saved choices |
+| `restoreState(input)` | Validates and replaces all choices from trusted persistence, preserving policy and recorded versions |
+| `subscribe(listener)` | Registers a synchronous invalidation callback and returns an idempotent unsubscribe function |
+
+The root also exports these types: `ConsentDecision`, `ConsentPurpose`, `ConsentUse`, `ConsentPolicy`, `ConsentChoice`, `ConsentState`, `ConsentEvaluation`, `ConsentRequirement`, `ValidationIssue`, `ValidationResult<T>`, `CreateConsentOptions`, `ConsentRuntime`, `ConsentSnapshot`, `ConsentDecisionCommand`, `ConsentDecisionsCommand`, and `CategoryConsentCommand`.
+
+Pure helpers, standalone validators, schemas, and the subscription helper are internal. Deep imports are unsupported. Implementation is organized by domain:
+
+The root also exports `ConsentDecisionsCommand`. Optional window-local fetch/XHR interception lives in [`/enforcement/request-rules`](../../docs/consent-request-rules.md); explicit per-use guards remain the primary path.
+
+| Domain | Ownership |
+| --- | --- |
+| `src/policy/` | `ConsentPolicy`, `ConsentPurpose`, declared `ConsentUse` values, their schemas, structural policy validation, and equality |
+| `src/consent/` | User decisions/state, evaluation, requirements, decision commands, factory/snapshots/subscriptions, and consent-state validation |
+| `src/storage/` | Internal codec, explicit persistence, and storage adapters |
+| `src/enforcement/fetch/` | Explicit fetch guard, cancellation, errors, types and tests |
+| `src/enforcement/axios/` | Explicit Axios guard, cancellation, errors, types and tests |
+| `src/enforcement/script/` | External script loader, load readiness and owned-node cleanup |
+| `src/enforcement/iframe/` | External iframe mounting and owned browsing-context removal |
+| `src/enforcement/integration/` | Per-use SDK activation, teardown, status, and reload requirements |
+| `src/enforcement/providers/posthog/` | Strict lazy PostHog and explicit existing-SDK adapters |
+| `src/enforcement/markup/` | Inert marked-script/iframe scanning and dynamic observation |
+| `src/enforcement/dom/` | Private shared DOM ownership/validation helpers and lifecycle tests |
+| `src/enforcement/request/` | Private shared grant-period cancellation, permission checks, and disposal lifecycle for the request guards |
+| `src/enforcement/_utils/` | Private shared constructor validation, signal retention, and the guard error base |
+| `src/utils/validation.ts` | Generic schema primitives, `validateWithSchema`, `ValidationIssue`, and `ValidationResult` |
+
+Each domain keeps its types, schemas, and tests locally. Policy does not import consent or storage. Shared validation in `utils/validation.ts` imports only Zod Mini. Consent depends on policy to evaluate user choices. The factory behavior is unchanged; the public validation types are renamed from `ConsentValidationIssue`/`ConsentValidationResult` to `ValidationIssue`/`ValidationResult` without aliases; `ConsentUse` describes an app declaration, while `ConsentChoice` describes a user's decision about it. Internal `arePoliciesEqual()` compares validated declarations structurally, including purpose/use order and every field; it does not determine scope compatibility or whether renewed consent is needed.
+
+## Permissions and outstanding decisions
+
+### Purpose definitions
+
+Every policy declares `purposes: readonly ConsentPurpose[]` alongside `uses`. A purpose is `{ id, title, description }`; each use references one definition through `purposeId`. For example, PostHog and Umami audience-measurement uses can reference the same purpose while retaining distinct use IDs, versions, and choices. Sharing a purpose never shares a grant. Services performing independently gated activities need separate uses.
+
+Purpose IDs are app-defined nonempty strings, not a closed built-in union. Custom and unused definitions are allowed; duplicate purpose IDs and undeclared references are rejected. Core does not infer purpose meaning, supply a provider catalog, or perform scope analysis. Human-readable descriptions remain necessary; an identifier is not a full disclosure or consent record.
+
+Purpose-only edits update the snapshot and notify subscribers, but do not automatically change permission. When a purpose change alters consent scope, the integrator/platform must review every referencing use and supply the appropriate new use or `consentVersion`. Cosmetic wording changes can retain versions. Core cannot infer that distinction from text.
+
+### Permission checks
+
+`getMismatchedConsent()` replaces `getRequirements()` without an alias. Despite the name, it includes undecided uses as well as version-mismatched grants.
+
+| Condition | Evaluation |
+| --- | --- |
+| Use is absent from the active policy, even if a saved grant exists | `allowed: false`, `reason: 'unknown-use'` |
+| Use has no choice | `allowed: false`, `reason: 'undecided'` |
+| Choice is denied, regardless of version | `allowed: false`, `reason: 'denied'` |
+| Grant version differs from the current use's version | `allowed: false`, `reason: 'consent-version-mismatch'` |
+| Grant version matches | `allowed: true` |
+
+Consent is recorded per use, not as blanket permission for a service or category. Separate uses of one service can have independent decisions and categories. `consentVersion` identifies one use's consent scope, independently of package versions or other uses. Both older and newer mismatched grants are blocked. Core does not calculate versions, infer semantic scope compatibility, or determine which changes legally require renewed consent.
+
+A policy update alone does not invalidate unchanged uses. Wording-only changes can preserve a version when they preserve scope. A mismatch does not erase or retroactively revoke the saved decision; it means that decision does not authorize the current version. Core cannot partially authorize an expanded use: independently gated activities need separate uses.
+
+`getMismatchedConsent()` returns readonly `ConsentRequirement` values with `useId`, `categoryId`, the current `consentVersion`, and reason `undecided` or `consent-version-mismatch`. Matching grants and all denials are omitted. Removed-use choices are ignored without deletion. Empty policies produce an empty list.
+
+An empty result is not blanket permission: all-denied states also have no outstanding decisions. Use `evaluate()` for permission checks. Requirements are derived data, not persisted state, UI commands, or mandatory user actions. The application decides whether and when to prompt.
+
+## Decisions and policy changes
+
+`currentAppPolicy` is the active app policy supplied at creation or through `updatePolicy()`. `userConsentedPolicy` is the policy scope shown for the submitted decision, including a denial; its name does not mean every use was granted. Capture it when opening the prompt. It is command input, not a second snapshot field or a stored historical policy. See the [consent terminology dictionary](../../docs/consent-terminology.md).
+
+All mutation methods return `ValidationResult<ConsentSnapshot>`. Decisions must be exactly `granted` or `denied`; no choice means undecided.
+
+Each decision must explicitly carry the policy shown to the user. The runtime validates that policy's structure, not proof that it was displayed or approved. It applies decisions to the latest state using the presented versions while leaving the active policy in place. If the policy changes while a prompt is open, accepting the older prompt cannot authorize unseen new uses or changed versions.
+
+A category decision creates individual choices only for that category's uses in the presented policy. A future member does not inherit a grant or denial. Use `setConsentDecision()` when the prompt covers just one new or changed use. Never replay a previous acceptance after a policy change or treat UI drafts as applied decisions.
+
+Decisions preserve unrelated and removed-use choices and existing choice order; new choices append in presented-policy order. Removed uses remain blocked by active-policy evaluation. `updatePolicy()` preserves every saved choice, including denials and mismatched versions.
+
+`restoreState(unknown)` validates and atomically restores a trusted saved choices record into an existing runtime. It does not replace `currentAppPolicy`, change consent versions, perform I/O, or constitute a new user decision. Malformed records change nothing; equal choices preserve snapshot identity and do not notify. Existing guards respond to effective restorations through their existing subscriptions. The optional `/storage/sync` entry uses this method for [cross-tab synchronization](../../docs/consent-sync.md), with explicit save-then-notify and protection for unsaved local decisions.
+
+This trusted-persistence method intentionally permits full state replacement, replacing the earlier no-arbitrary-replacement invariant. It retains unknown/removed-use choices for compatibility, but evaluation still blocks unknown uses and mismatched grants. Validation does not prove that the user made those choices; applications must provide trusted saved records and use the presented-policy decision commands for new user input.
+
+Malformed commands or policies return issues without changing state, references, or notifications. Structurally valid commands targeting a use or category absent from their presented policy throw `Error` without changing the runtime.
+
+## Validation and snapshots
+
+Creation validates both policy and initial state. Decision methods validate the entire command and presented policy; `updatePolicy()` validates the replacement policy. There are no public standalone validation methods.
+
+- Objects and arrays must have the declared structure; unexpected fields are rejected.
+- Policy/state identifiers, purpose titles, and descriptions must contain a non-whitespace character. Values are preserved exactly, without trimming, conversion, or coercion.
+- Versions must be positive safe integers.
+- Policy purpose IDs, policy use IDs, and state choice use IDs must each be unique, even for identical duplicates. Every use's `purposeId` must exactly match a declared purpose ID.
+- Empty arrays are valid; missing arrays are not defaulted.
+- Initial-state validation is independent of the policy and preserves removed-use and mismatched choices.
+
+Issues contain a `code`, string/number `path` segments, and a `message`, not raw Zod errors or copies of rejected data. Nested creation issues retain `currentAppPolicy` or `initialState` path prefixes. Inputs must be decoded JSON-like data, not JSON strings or arbitrary executable objects; caller-defined throwing getters/proxies are not caught. Validation does not authenticate saved choices or establish consent evidence.
+
+Snapshots and requirements are detached and frozen at every object/array level. The runtime's method object is frozen too. Caller inputs are neither mutated nor frozen. Methods are stable and work without `this` binding. Instances are independent; do not share a mutable instance across unrelated server requests or users.
+
+Identical decision/version updates and structurally equivalent policies are no-ops: snapshot/requirements identity is retained and subscribers are not notified. Policy property insertion order is ignored; purpose/use array order and every definition/declaration field remain significant.
+
+## Subscriptions
+
+Effective changes atomically publish the new snapshot and requirements before synchronous notification. A category update publishes once.
+
+Subscribers are not called at registration or on reads. Duplicate registrations are independent. Notifications follow registration order; removed listeners are skipped, and listeners added during delivery join the next pass.
+
+Reentrant mutations commit immediately and request another notification pass instead of recursively invoking listeners. Notifications mean "read the latest snapshot," not a history of every intermediate transition. A mutation's success result contains its own committed snapshot, which may precede a later reentrant change. Subscribers must not unconditionally write on every notification.
+
+Synchronous listener failures do not roll back a commit or skip other active listeners. After notification passes finish, the originating mutation throws an `AggregateError` containing those failures. Inspect the current snapshot rather than assuming the mutation failed to apply. Subscribers handle their own asynchronous errors; callback return values are ignored.
+
+## Migration from standalone functions
+
+Policies now require `purposes`, even when empty, and uses require `purposeId` instead of `purpose`. Move existing purpose text into a declared definition's `description`, supply a `title` and stable `id`, and reference that ID from the use. There are no legacy aliases or automatic conversions. Preserve existing use IDs and versions when this is only a structural migration of unchanged scope. The V1 stored choices format is unchanged and contains no purpose definitions.
+
+Creation and snapshots now use `currentAppPolicy` instead of `policy`; decision commands use `userConsentedPolicy` instead of `presentedPolicy`. The old fields are rejected, with no compatibility aliases. `ConsentPolicy` and `updatePolicy()` retain their names; decision and evaluation behavior is unchanged.
+
+Replace standalone evaluation and requirements calls with `consent.evaluate(useId)` and `consent.getMismatchedConsent()`. Replace standalone setters with the corresponding instance methods, passing `userConsentedPolicy` explicitly instead of `policy` and `state`. Pass decoded policy/state into `createConsent()`; creation and mutations perform validation.
+
+The former evaluation reason `outdated` is `consent-version-mismatch`, with no legacy alias. Update exhaustive switches and reason comparisons.
+
+## Internal persisted format
+
+The storage domain contains internal `encodeConsentState(unknown)` and `decodeConsentState(unknown)` helpers. These are not root exports or supported deep imports. `createConsentStorage(adapter)` exposes explicit async `load()`/`save(state)` through `@peax/consent-core/storage`, reusing this codec without changing the synchronous consent factory. The same subpath exports `createLocalStorageAdapter` and `createFetchStorageAdapter`; `/storage/localforage` exports `createLocalForageAdapter` with a lazy optional peer. Apps still decide when to load/save. See [Consent storage](../../docs/consent-storage.md) for examples, results, HTTP protocol, and failure/ordering guarantees.
+
+Version 1 is a strict JSON record containing only `{ formatVersion: 1, state: { choices: [...] } }`. `formatVersion` identifies the wire structure, independently of each choice's `consentVersion`. Neither policy, derived permissions, nor requirements are persisted. This is preference state, not authenticated consent evidence or a policy history.
+
+Encoding validates decoded JSON-like state before serializing. Decoding requires a string, parses JSON, checks the positive safe integer format version, then validates the original record using its strict version-specific schema. Both use the existing `ValidationResult` contract. Non-string input returns `invalid_type`; broken JSON returns `invalid_json`; an unsupported positive safe integer version returns `unsupported_format_version` at `['formatVersion']`. Missing/malformed versions and malformed V1 records return structural issues. Nested state issues retain their `state` prefix; rejected values and raw parsing errors are not returned.
+
+Empty choices are valid. Duplicate choices, unexpected fields, and invalid decisions or versions are rejected without coercion, repair, or an empty-state fallback. Unknown format versions are not interpreted as V1. Absence of a stored record is a separate caller concern; the codec does not delete or overwrite failed records.
+
+Successful decoding returns detached, deeply frozen state. Choice order, exact IDs, grants, denials, removed-use choices, and mismatched consent versions are preserved. Only evaluation against `currentAppPolicy` determines permission after restoration. The codec performs no I/O, runtime mutations, or subscription notifications. Expiry, migrations and automatic saving remain deferred. Cross-tab synchronization is separately opt-in under `/storage/sync`; V1's wire shape is unchanged and must remain stable if the in-memory model changes later.
+
+## Boundaries and package cost
+
+Storage I/O and cross-tab synchronization are opt-in through separate storage entries; no Peax service is required. Explicit request blocking/cancellation, script/iframe loading, integration lifecycles/PostHog shutdown hooks, and marked-HTML scanning use their own subpaths. Unmarked resources remain outside DOM guard scope; optional window-local fetch/XHR interception is provided separately by `/enforcement/request-rules`. There is no automatic saving, automatic banner opening or React code in Core; the separate React bindings remain optional. The internal codec only converts state and JSON. Subscriptions are not an audit log. Tracker classification, legal conclusions and policy approval remain outside Core.
+
+Zod Mini is an external runtime dependency of the factory. The reviewed 4 KB root ceiling excludes Zod; packed-consumer verification separately reports the complete factory bundle including dependencies. The former pure-function-only and standalone-validation bundle profiles no longer describe supported public APIs. No global Zod configuration or locale is installed.
+
+Core now provides persistence adapters and framework-independent fetch/Axios guards. The additive pre-release `/enforcement/fetch` entry exports `createConsentFetch`, `ConsentFetchError`, and the readonly `ConsentFetch`, `ConsentFetchOptions`, and `ConsentFetchErrorReason` types. `/enforcement/axios` similarly exports `createConsentAxios`, `ConsentAxiosError`, `ConsentAxios`, `ConsentAxiosOptions`, and `ConsentAxiosErrorReason`; Axios `^1.20.0` is an optional external peer. The additive atomic submission API has a reviewed 4 KB root ceiling; optional request rules have a reviewed 6 KB closure ceiling. Size checks include shared output chunks per entry, with unchanged separate budgets for storage, localForage, dependency-free fetch (2.25 KB), and Axios enforcement (2.75 KB excluding Axios). Clean consumers verify SSR-safe imports with and without optional peers, declarations, browser persistence, and request enforcement. See the canonical [package contracts](../../docs/engineering/package-contracts.md) before extending the API.
+
+The additive `/enforcement/script` and `/enforcement/iframe` entries expose `createConsentScript`/`createConsentIframe`, their error classes, and readonly guard, factory options, load/mount options, handle and error-reason types. They add no dependencies and have 3 KB/2.75 KB Brotli budgets respectively, including their shared DOM and internal chunks. Browser tests cover script execution/storage/SRI, cross-origin iframe activity, ownership cleanup and explicit script-shutdown limitations. Full usage and pre-release API notes are in [the DOM guard guide](../../docs/consent-dom.md).
+
+Pre-release correctness fixes: integration/markup listener failures no longer interrupt lifecycle cleanup; failed markup startup rolls back all managed resources while retaining script reload/no-replay state. Single-use/category commands reject blank identifiers through validation issues instead of unknown-target exceptions. Public exports and existing size budgets are unchanged. See [integration notification handling](../../docs/consent-integrations.md) and [markup rollback](../../docs/consent-markup.md).

package/dist/ConsentEnforcementError-Bn_ayWJI.js

@@ -0,0 +1,16 @@
+//#region src/enforcement/_utils/ConsentEnforcementError.ts
+/**
+* Shared shape for enforcement guard errors. Only the concrete classes are public: each subpath
+* exports exactly one of them, so consumers keep their own `instanceof` and literal `name` type.
+*/
+var ConsentEnforcementError = class extends Error {
+	useId;
+	reason;
+	constructor(message, useId, reason) {
+		super(message);
+		this.useId = useId;
+		this.reason = reason;
+	}
+};
+//#endregion
+export { ConsentEnforcementError as t };

package/dist/assertStorageIdentifier-BQuj-9bp.js

@@ -0,0 +1,7 @@
+//#region src/storage/assertStorageIdentifier.ts
+/** Adapter configuration is typed programmer input; persisted data uses the codec. */
+function assertStorageIdentifier(value, label = "storage key or URL") {
+	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`Expected a nonempty ${label}.`);
+}
+//#endregion
+export { assertStorageIdentifier as t };

package/dist/createConsentIframe-Bw-cl--m.js

@@ -0,0 +1,93 @@
+import { t as ConsentEnforcementError } from "./ConsentEnforcementError-Bn_ayWJI.js";
+import { a as setReferrerPolicy, i as requireText, n as insertGuarded, o as setStringAttribute, r as requireParent, s as sourceUrl, t as createDomGuard } from "./createDomGuard-CuIEC0HP.js";
+//#region src/enforcement/iframe/ConsentIframeError.ts
+var ConsentIframeError = class extends ConsentEnforcementError {
+	name = "ConsentIframeError";
+	constructor(useId, reason) {
+		super(`Consent iframe blocked (${reason}).`, useId, reason);
+	}
+};
+//#endregion
+//#region src/enforcement/iframe/iframePresentation.ts
+function readIframePresentation({ title, width, height }) {
+	requireText(title, "iframe title");
+	for (const [name, value] of [["width", width], ["height", height]]) if (value !== void 0 && typeof value !== "string") throw new TypeError(`Expected a string ${name}.`);
+	return {
+		title,
+		width,
+		height
+	};
+}
+function applyIframePresentation(element, options) {
+	element.title = options.title;
+	for (const name of ["width", "height"]) {
+		const value = options[name];
+		if (value === void 0) element.removeAttribute(name);
+		else setStringAttribute(element, name, value);
+	}
+}
+//#endregion
+//#region src/enforcement/iframe/createIframeElement.ts
+function createIframeElement(options) {
+	const presentation = readIframePresentation(options);
+	const { src, parent, sandbox, allow, referrerPolicy, loading = "eager" } = options;
+	requireParent(parent);
+	if (loading !== "eager" && loading !== "lazy") throw new TypeError("Expected eager or lazy loading.");
+	const url = sourceUrl(src, parent);
+	const element = parent.ownerDocument.createElement("iframe");
+	applyIframePresentation(element, presentation);
+	setStringAttribute(element, "sandbox", sandbox);
+	setStringAttribute(element, "allow", allow);
+	setStringAttribute(element, "loading", loading);
+	setReferrerPolicy(element, referrerPolicy);
+	return {
+		element,
+		parent,
+		url
+	};
+}
+//#endregion
+//#region src/enforcement/iframe/createConsentIframe.ts
+/** Owns only frames explicitly mounted through this guard; never scans or patches the page. */
+function createConsentIframe({ consent, useId }) {
+	const owner = createDomGuard(consent, useId, (reason) => new ConsentIframeError(useId, reason));
+	return Object.freeze({
+		mount(options) {
+			const check = owner.begin();
+			const { element, parent, url } = createIframeElement(options);
+			check();
+			let removed = false;
+			const remove = () => {
+				if (removed) return;
+				removed = true;
+				forget();
+				element.remove();
+			};
+			const forget = owner.track(remove);
+			try {
+				insertGuarded(element, parent, url, check);
+			} catch (error) {
+				remove();
+				throw error;
+			}
+			const checkMounted = () => {
+				check();
+				if (removed) throw new ConsentIframeError(useId, "removed");
+			};
+			return Object.freeze({
+				element,
+				remove,
+				updatePresentation(options) {
+					checkMounted();
+					const presentation = readIframePresentation(options);
+					checkMounted();
+					applyIframePresentation(element, presentation);
+					checkMounted();
+				}
+			});
+		},
+		dispose: owner.dispose
+	});
+}
+//#endregion
+export { ConsentIframeError as n, createConsentIframe as t };

package/dist/createConsentRequestScope-D7U8uK6m.js

@@ -0,0 +1,58 @@
+//#region src/enforcement/_utils/signalRetention.ts
+/**
+* Keeps a composed AbortSignal reachable from the native objects it guards.
+*
+* WebKit can lose a composed signal after headers when JS no longer retains it, so the signal is
+* weakly associated with its response/body instead of being held in a permanent per-guard request
+* list. Weak keys never keep completed responses or streams alive, and the association is only
+* ever written: it exists to retain, not to be read back.
+*
+* The observable guarantee (cancellation stays connected for response bodies, clones and readers
+* after headers resolve) is verified by the browser fixtures, which cannot be reproduced in jsdom.
+*/
+var signals = /* @__PURE__ */ new WeakMap();
+/** Retains `signal` for as long as any supplied owner stays reachable. Absent owners are skipped. */
+function retainSignal(signal, ...owners) {
+	for (const owner of owners) if (owner) signals.set(owner, signal);
+}
+//#endregion
+//#region src/enforcement/request/createConsentRequestScope.ts
+/** Private grant-period cancellation shared by request guards, not transport dispatch. */
+function createConsentRequestScope(consent, useId, createError) {
+	let disposed = false;
+	let controller;
+	function cancel(error) {
+		const previous = controller;
+		controller = void 0;
+		previous?.abort(error);
+	}
+	function evaluate() {
+		const result = consent.evaluate(useId);
+		if (!result.allowed) cancel(createError(result.reason));
+		return result;
+	}
+	function assertAllowed() {
+		if (disposed) throw createError("disposed");
+		const result = evaluate();
+		if (!result.allowed) throw createError(result.reason);
+	}
+	const unsubscribe = consent.subscribe(() => {
+		if (!disposed) evaluate();
+	});
+	return {
+		assertAllowed,
+		begin() {
+			assertAllowed();
+			controller ??= new AbortController();
+			return controller.signal;
+		},
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			unsubscribe();
+			cancel(createError("disposed"));
+		}
+	};
+}
+//#endregion
+export { retainSignal as n, createConsentRequestScope as t };