fix(core): stage preference toggles in a draft until save (#162)

Author: jamiedavenport

.changeset/staged-consent-toggles.md

@@ -0,0 +1,12 @@
+---
+"@policystack/core": minor
+"@policystack/react": minor
+"@policystack/vue": minor
+"@policystack/svelte": minor
+"@policystack/solid": minor
+"@policystack/angular": minor
+---
+
+Consent preference toggles are now staged. `toggle()` writes to `state.draft` instead of live decisions, and nothing is gated, persisted, or script-loaded until `save()` promotes the draft in one step — scripts no longer load on checkbox tick before "Save", and returning visitors no longer get their stored record rewritten on every tick (#157). Leaving the preferences route without saving discards the draft.
+
+API changes: `toggle(key)` no longer accepts `ActionOptions` (name the record source at `save()` instead), and `ConsentState` gains a required `draft` field. Per-category `granted` accessors in all framework bindings read `draft ?? decisions` so checkboxes respond instantly; custom panels rendering checkboxes from raw `decisions` should apply the same merge.

apps/web/content/blog/astro-cookie-banner.mdx

@@ -144,7 +144,8 @@ Astro's `<script>` tags are bundled by Vite, so this looks like a normal module
     prefs.hidden = state.route !== "preferences";
     for (const cb of checkboxes) {
       const key = cb.dataset.category;
-      if (key) cb.checked = state.decisions[key] ?? false;
+      // draft holds staged (unsaved) toggles; decisions is what save() applied.
+      if (key) cb.checked = (state.draft ?? state.decisions)[key] ?? false;
     }
   };
   store.subscribe(render);

apps/web/content/docs/consent/angular.md

@@ -77,14 +77,16 @@ export class BannerComponent {
 }
 ```
 
-Signal properties: `route`, `categories`, `decisions`, `jurisdiction`, `policyVersion`, `decidedAt`, `repromptReason`, `state`.
+Signal properties: `route`, `categories`, `decisions`, `draft`, `jurisdiction`, `policyVersion`, `decidedAt`, `repromptReason`, `state`.
 
 Methods: `acceptAll`, `acceptNecessary`, `reject`, `toggle`, `save`, `setRoute`, `has`, `getConsentRecord`, `getPreviousRecord`.
 
 ### `injectCategory(key)`
 
 Granular per-category access. Must be called inside an injection context (e.g. a component constructor or field initializer).
 
+`toggle` stages the change and `granted()` reflects it instantly (it reads the pending `state.draft`), but nothing is applied — `has()`, `<ConsentGate>`, script gating, and storage only change when `save()` promotes the draft. Leaving the preferences route without saving discards it.
+
 ```ts
 import { Component } from "@angular/core";
 import { injectCategory } from "@policystack/angular/consent";

apps/web/content/docs/consent/core.md

@@ -35,6 +35,12 @@ store.acceptAll();
 
 The store's surface: `getState()`, `subscribe()`, `acceptAll()`, `acceptNecessary()`, `reject()`, `toggle(key)`, `save()`, `setRoute()`, `has(expr)`, `getConsentRecord()`, `getPreviousRecord()`, `refreshJurisdiction()`. See [`types.ts`](./src/types.ts) for the full shape.
 
+### Staged preferences (`state.draft`)
+
+`toggle(key)` never changes live consent. It stages the flip in `state.draft`, and gating (`has()` / `<ConsentGate>`), storage, and gated scripts keep reading `decisions` until `save()` promotes the draft in one step and stamps `decidedAt`. Leaving the preferences flow without saving — any `setRoute` that does not land on `"preferences"` — discards the draft, so "Back" genuinely abandons unsaved edits and nothing was loaded or persisted in the meantime.
+
+Render preference checkboxes from `draft ?? decisions` so the panel responds instantly; the framework bindings' per-category `granted` accessor does exactly this.
+
 ## Storage adapters
 
 Decisions persist via a `StorageAdapter` passed to `createConsentStore({ adapter })`. Three adapters ship as subpath imports:
@@ -104,7 +110,7 @@ const store = createConsentStore({ categories });
 // Brave (and any browser asserting GPC) starts with all opt-outs denied.
 ```
 
-Once a user makes an explicit decision (`acceptAll`, `toggle`, etc.) the resulting record has `state.source === "user"` and is preserved on reload — `applyGPC` will not overwrite it.
+Once a user makes an explicit decision (`acceptAll`, `save`, etc.) the resulting record has `state.source === "user"` and is preserved on reload — `applyGPC` will not overwrite it.
 
 To scope GPC to the legally-required US states only:
 
@@ -158,7 +164,7 @@ type ConsentRecord = {
 - `"api"` — set via a programmatic call (override with `acceptAll({ source: "api" })`, etc.).
 - `"import"` — migrated from a legacy or unrecognised record.
 
-The store infers `source` from `state.route` at the moment the decision is taken; pass `{ source }` to any action to override it.
+The store infers `source` from `state.route` at the moment the decision is taken; pass `{ source }` to any decision action (`acceptAll`, `acceptNecessary`, `reject`, `save`) to override it. `toggle` takes no options — it only stages a draft, and the eventual `save` names the source.
 
 Read the current record via `store.getConsentRecord()` (or the binding-level `useConsent().getConsentRecord()`). It returns `null` until a decision has been recorded.
 
@@ -184,7 +190,7 @@ store.getConsentRecord();
 
 Records produced by older versions of Consent are tolerated on read: missing fields fall back to safe defaults, the legacy `source: "user"` flag is mapped to `"banner"`, and any other unrecognised legacy source becomes `"import"`. The next user decision rewrites the record in the v1 shape.
 
-GPC alone does not produce a record — the visitor has not made a decision. `getConsentRecord()` keeps returning `null` until the user accepts, rejects, saves, or toggles a category.
+GPC alone does not produce a record — the visitor has not made a decision. `getConsentRecord()` keeps returning `null` until the user accepts, rejects, or saves their preference changes.
 
 ## Re-consent triggers
 

apps/web/content/docs/consent/react.md

@@ -59,6 +59,8 @@ function Banner() {
 
 Granular per-category access. Returns `{ granted, toggle }`.
 
+`toggle` stages the change and `granted` reflects it instantly (it reads the pending `state.draft`), but nothing is applied — `has()`, `<ConsentGate>`, script gating, and storage only change when `save()` promotes the draft. Leaving the preferences route without saving discards it.
+
 ```tsx
 import { useCategory } from "@policystack/react/consent";
 

apps/web/content/docs/consent/solid.md

@@ -63,6 +63,8 @@ function Banner() {
 
 Granular per-category access.
 
+`toggle` stages the change and `granted()` reflects it instantly (it reads the pending `state.draft`), but nothing is applied — `has()`, `<ConsentGate>`, script gating, and storage only change when `save()` promotes the draft. Leaving the preferences route without saving discards it.
+
 ```tsx
 import { useCategory } from "@policystack/solid/consent";
 

apps/web/content/docs/consent/svelte.md

@@ -65,6 +65,8 @@ Returns a reactive object whose properties are tracked via `$state`. Read direct
 
 Granular per-category access.
 
+`toggle` stages the change and `granted` reflects it instantly (it reads the pending `state.draft`), but nothing is applied — `has()`, `<ConsentGate>`, script gating, and storage only change when `save()` promotes the draft. Leaving the preferences route without saving discards it.
+
 ```svelte
 <script lang="ts">
   import { getCategory } from "@policystack/svelte/consent";

apps/web/content/docs/consent/vue.md

@@ -59,6 +59,8 @@ const { route, decisions, acceptAll, acceptNecessary, setRoute } = useConsent();
 
 Granular per-category access. Returns a `granted` computed and a `toggle` action.
 
+`toggle` stages the change and `granted` reflects it instantly (it reads the pending `state.draft`), but nothing is applied — `has()`, `<ConsentGate>`, script gating, and storage only change when `save()` promotes the draft. Leaving the preferences route without saving discards it.
+
 ```vue
 <script setup lang="ts">
 import { useCategory } from "@policystack/vue/consent";

packages/angular/src/category.ts

@@ -6,10 +6,12 @@ export type CategoryRef = {
 	toggle: () => void;
 };
 
+// `granted` is the checkbox view and includes staged draft edits; effective
+// consent (`has()` / <ConsentGate>) only moves on save().
 export function injectCategory(key: string): CategoryRef {
 	const consent = inject(ConsentService);
 	return {
-		granted: computed(() => consent.decisions()[key] === true),
+		granted: computed(() => (consent.draft() ?? consent.decisions())[key] === true),
 		toggle: () => consent.toggle(key),
 	};
 }

packages/angular/src/consent.service.ts

@@ -21,6 +21,7 @@ export class ConsentService {
 	readonly route: Signal<Route> = computed(() => this._state().route);
 	readonly categories: Signal<Category[]> = computed(() => this._state().categories);
 	readonly decisions: Signal<Record<string, boolean>> = computed(() => this._state().decisions);
+	readonly draft: Signal<Record<string, boolean> | null> = computed(() => this._state().draft);
 	readonly jurisdiction: Signal<JurisdictionId | null> = computed(() => this._state().jurisdiction);
 	readonly policyVersion: Signal<string> = computed(() => this._state().policyVersion);
 	readonly decidedAt: Signal<string | null> = computed(() => this._state().decidedAt);
@@ -45,8 +46,8 @@ export class ConsentService {
 		this.store.reject(opts);
 	}
 
-	toggle(category: string, opts?: ActionOptions): void {
-		this.store.toggle(category, opts);
+	toggle(category: string): void {
+		this.store.toggle(category);
 	}
 
 	save(opts?: ActionOptions): void {