@quran-lab/tajweedformer 2.0.0 → 2.0.1

package/web/consent/element.js

@@ -1,13 +1,15 @@
 // <quranlab-consent> and <quranlab-sharing-settings>: the SDK's own sharing sheet and settings for
-// the browser (SHARING_EXPERIENCE.md, PLATFORM_CLIENT.md section 9). Themable with CSS custom
-// properties (--ql-bg, --ql-fg, --ql-muted, --ql-accent, --ql-accent-fg, --ql-radius, --ql-font) and
-// ::part(sheet|title|body|primary|secondary|guardian), RTL from the deck's direction, keyboard and
-// screen reader friendly (a modal <dialog>), two buttons of equal weight, nothing pre-ticked.
+// the browser (SHARING_EXPERIENCE.md, PLATFORM_CLIENT.md section 9). Themable with a `theme` (theme.js) or
+// the CSS custom properties it sets (--ql-bg, --ql-fg, --ql-muted, --ql-accent, --ql-accent-fg, --ql-radius,
+// --ql-font, --ql-title-font) and ::part(sheet|title|body|primary|secondary|guardian), RTL from the deck's
+// direction, keyboard and screen reader friendly (a modal <dialog>), two buttons of equal weight, nothing
+// pre-ticked. An app's own wording (wording.js) is shown in place of the deck's strings it replaces.
 //
 //   import '@quran-lab/tajweedformer/consent';         // defines the elements
-//   const yes = await QuranLabConsent.ask({ lang: 'ar', variant: 'first', guardian: false });
+//   const yes = await QuranLabConsent.ask({ lang: 'ar', variant: 'first', guardian: false, theme: { accent: '#0b6e4f' } });
 
 import { copyFor } from './copy.js';
+import { applyTheme } from './theme.js';
 
 const STYLE = `
 :host { all: initial; }
@@ -18,7 +20,7 @@ dialog { box-sizing: border-box; max-inline-size: min(34rem, calc(100vw - 2rem))
   box-shadow: 0 20px 60px rgb(0 0 0 / .25); }
 dialog::backdrop { background: rgb(0 0 0 / .45); }
 
-h2 { margin: 0 0 .75rem; font-size: 1.25rem; line-height: 1.3; font-weight: 650; }
+h2 { margin: 0 0 .75rem; font-size: 1.25rem; line-height: 1.3; font-weight: 650; font-family: var(--ql-title-font, inherit); }
 p { margin: 0 0 .75rem; }
 .muted { color: var(--ql-muted, inherit); opacity: .85; font-size: .95rem; }
 ul { margin: 0 0 1rem; padding-inline-start: 1.1rem; }
@@ -51,7 +53,8 @@ const Base = globalThis.HTMLElement || class {};
 export class QuranLabConsent extends Base {
   /**
    * Show the sheet and resolve with the learner's answer (true = share). Dismissing (Escape) is "Not now".
-   * @param {{ lang?: string, variant?: 'first'|'reask'|'version', guardian?: boolean, parent?: Element }} o
+   * @param {{ lang?: string, variant?: 'first'|'reask'|'version', guardian?: boolean, parent?: Element,
+   *           wording?: Record<string, string>|null, theme?: object|null }} o
    * @returns {Promise<{ yes: boolean, guardianConfirmed: boolean }>}
    */
   static ask(o = {}) {
@@ -60,8 +63,9 @@ export class QuranLabConsent extends Base {
     return el.show(o).finally(() => el.remove());
   }
 
-  show({ lang = (globalThis.navigator && navigator.language) || 'en', variant = 'first', guardian = false } = {}) {
-    const c = copyFor(lang);
+  show({ lang = (globalThis.navigator && navigator.language) || 'en', variant = 'first', guardian = false, wording = null, theme = null } = {}) {
+    const c = copyFor(lang, wording);
+    applyTheme(this, theme);
     const t = c.t;
     const root = this.shadowRoot || this.attachShadow({ mode: 'open' });
     const lines = (guardian ? ['sheet.what', 'sheet.who', 'sheet.control'] : ['sheet.mistakes', 'sheet.what', 'sheet.who', 'sheet.control'])
@@ -101,13 +105,14 @@ export class QuranLabConsent extends Base {
   }
 
   /** The one-time thank-you, as a small dismissable note. */
-  static thank({ lang, parent, ms = 6000 } = {}) {
-    const c = copyFor(lang || (globalThis.navigator && navigator.language) || 'en');
+  static thank({ lang, parent, ms = 6000, wording = null, theme = null } = {}) {
+    const c = copyFor(lang || (globalThis.navigator && navigator.language) || 'en', wording);
     const el = document.createElement('div');
     el.setAttribute('role', 'status');
     el.lang = c.lang; el.dir = c.dir;
     el.textContent = c.t('thanks');
-    el.style.cssText = 'position:fixed;inset-inline:1rem;inset-block-end:1rem;max-inline-size:32rem;margin-inline:auto;padding:1rem 1.25rem;border-radius:14px;background:var(--ql-accent,#2a3b8f);color:var(--ql-accent-fg,#fff);font:500 1rem/1.5 var(--ql-font,system-ui,sans-serif);z-index:2147483647;box-shadow:0 10px 30px rgb(0 0 0 / .25)';
+    el.style.cssText = 'position:fixed;inset-inline:1rem;inset-block-end:1rem;max-inline-size:32rem;margin-inline:auto;padding:1rem 1.25rem;border-radius:var(--ql-radius,14px);background:var(--ql-accent,#2a3b8f);color:var(--ql-accent-fg,#fff);font:500 1rem/1.5 var(--ql-font,system-ui,sans-serif);z-index:2147483647;box-shadow:0 10px 30px rgb(0 0 0 / .25)';
+    applyTheme(el, theme);
     (parent || document.body).appendChild(el);
     setTimeout(() => el.remove(), ms);
     return el;
@@ -124,7 +129,8 @@ export class QuranLabSharingSettings extends Base {
   connectedCallback() { this.render(); }
   render() {
     if (!this._c) return;
-    const c = copyFor(this.getAttribute('lang') || this._c.lang);
+    const c = copyFor(this.getAttribute('lang') || this._c.lang, this._c.wording || null);
+    applyTheme(this, this._c.theme || null);
     const t = c.t;
     const root = this.shadowRoot || this.attachShadow({ mode: 'open' });
     const on = this._c.state.sharing;
@@ -135,7 +141,7 @@ export class QuranLabSharingSettings extends Base {
     <input type="checkbox" role="switch" id="s" ${on ? 'checked' : ''} aria-checked="${on}"></div>
   ${this._c.state.guardianVariant ? `<label class="guardian"><input type="checkbox" id="g"> <span>${esc(t('sheet.guardian.confirm'))}</span></label>` : ''}
   <details><summary>${esc(t('settings.what'))}</summary><p>${esc(t('what.detail'))}</p></details>
-  ${code ? `<details id="rc"><summary>Recovery code</summary><p class="code" id="code"></p></details>` : ''}
+  ${code ? `<details id="rc"><summary>${esc(t('recovery.reveal'))}</summary><p class="code" id="code"></p><p class="muted">${esc(t('recovery.keep'))}</p><p class="muted">${esc(t('recovery.hint'))}</p></details>` : ''}
   <div class="row"><button class="secondary" id="del">${esc(t('settings.delete'))}</button></div>
   <p class="muted" id="msg" role="status"></p>
 </section>`;
@@ -151,7 +157,7 @@ export class QuranLabSharingSettings extends Base {
     root.querySelector('#del').addEventListener('click', async () => {
       if (!globalThis.confirm || globalThis.confirm(t('delete.confirm'))) {
         const ok = await this._c.deleteShared().then(() => true, () => false);
-        msg.textContent = ok ? t('delete.done') : t('delete.confirm');
+        msg.textContent = ok ? t('delete.done') : t('delete.failed.network');
         if (ok) this.render();
       }
     });

package/web/consent/index.d.ts

@@ -1,45 +1,107 @@
 // Types for @quran-lab/tajweedformer/consent: the recitation sharing experience (SHARING_EXPERIENCE.md).
 import type { QuranLab, StateStore } from '../platform/index.js';
 
+/** 'first', or 'reask' after "Not now". 'version' is deprecated and never produced since 2.0.1: a grant is kept
+ * across decks and wordings and is never asked about again. */
 export type AskVariant = 'first' | 'reask' | 'version';
 export interface Ask { variant: AskVariant; guardian: boolean }
 export interface Answer { yes: boolean; guardianConfirmed?: boolean }
 
+/** sheets shown in all per install, ever (the first ask and at most two re-asks after "Not now") */
 export declare const MAX_ASKS: 3;
+/** sessions between asks */
 export declare const REASK_GAP: 7;
+/** the consent version a 2.0.0 grant stored without a version was given to (the deck 2.0.0 bundled) */
+export declare const LEGACY_CONSENT_VERSION: 'share-2026-11-07';
+/** the StateStore key of the sharing state (the same since 2.0.0) */
+export declare const SHARING_STATE_KEY: 'sharing.v1';
 
 export declare class SharingState {
-  constructor(state: StateStore, o?: { enabled?: () => boolean; consentVersion?: string; audience?: string; clock?: () => number });
-  /** uploads may run: allowed by the app and the signed config, and the learner said yes */
+  constructor(state: StateStore, o?: { enabled?: () => boolean; consentVersion?: string; consentTextSha256?: string | null; audience?: string; clock?: () => number });
+  /** uploads may run: allowed by the signed config, and the learner said yes (to whichever version) */
   readonly sharing: boolean;
   readonly guardianVariant: boolean;
-  /** a session ended; the ask due now, or null */
+  /** asking has not ended: no yes, not turned off, fewer than MAX_ASKS sheets shown */
+  readonly asking: boolean;
+  /** the version a new grant records */
+  readonly consentVersion: string | null;
+  readonly consentTextSha256: string | null;
+  /** the version the current grant was given to, as recorded then (null when not granted) */
+  readonly grantVersion: string | null;
+  /** the hash of the own wording the current grant was given to (null for a deck's wording or when not sharing) */
+  readonly grantTextSha256: string | null;
+  /** the version a new grant records; an existing grant keeps its own and is not asked again */
+  setConsent(version: string, textSha256?: string | null): void;
+  /** a session ended; the ask due now (counted as shown), or null */
   sessionCompleted(o?: { feedback?: boolean }): Ask | null;
-  askNow(): Ask;
+  /** the app's own timing: an ask counted as shown, or null once asking has ended */
+  askNow(): Ask | null;
   answer(yes: boolean, o?: { guardianConfirmed?: boolean }): 'granted' | 'declined' | 'final';
   setSharing(on: boolean, o?: { guardianConfirmed?: boolean }): void;
   takeThanks(): boolean;
   onChange(f: (s: object) => void): () => void;
 }
 
-/** A copy deck (quranlab.sharing-copy/1) for one language. */
+/** A copy deck (quranlab.sharing-copy/1) for one language, with any own wording applied. */
 export interface Deck {
   lang: string; dir: 'ltr' | 'rtl'; version: string; consentVersion: string; deleteDays: number;
+  /** 'immediate' since deck 2026-11-09.1 */
+  deleteTiming: string;
+  /** the keys the app's own wording replaces */
+  overridden: string[];
   hadithSource: { collection: string; number: number; url: string; translation_source: string | null; translated: boolean } | null;
-  /** a string by key ({days} filled); English when this deck lacks it */
+  /** a string by key: the app's own wording, else this deck's, else English */
   t(key: string): string;
   /** the plural impact line for real shared minutes */
   minutes(n: number): string;
 }
 export declare const EN: Readonly<{ format: string; version: string; lang: string; dir: string; consent_version: string; strings: Record<string, unknown> }>;
-export declare function copyFor(lang?: string): Deck;
+export declare function copyFor(lang?: string, overrides?: Record<string, string> | null): Deck;
+
+/** An app's own wording ({deck key: text}); plural lines as `impact.minutes.<category>`. */
+export type Wording = Record<string, string>;
+/** The consent a grant is to: the deck's version, or custom-<24 hex> with the text's SHA-256 and canonical text. */
+export interface Consent { version: string; textSha256: string | null; canonicalText: string | null }
+export declare const CONSENT_TEXT_FORMAT: 'quranlab.consent-text/1';
+export declare const PLURAL_CATEGORIES: readonly string[];
+/** checks overrides; throws a TypeError for an unknown key or an empty or blank text */
+export declare function validateWording(overrides: Wording | null | undefined): Readonly<Wording>;
+export declare function canonicalConsentText(base: string, overrides: Wording | null): string | null;
+export declare function deriveConsent(base: string, overrides: Wording | null): Consent;
+export declare function wordingKeys(): Set<string>;
+export declare function sha256HexSync(bytes: Uint8Array): string;
+
+/** The look of the SDK's sheets (consent, guardian, thanks, settings): CSS values; a number cornerRadius is px. */
+export interface SharingTheme {
+  accent?: string; accentText?: string; background?: string; text?: string; secondaryText?: string;
+  cornerRadius?: string | number; titleFont?: string; bodyFont?: string;
+}
+export declare const THEME_PROPERTIES: Readonly<Record<keyof SharingTheme, string>>;
+export declare function themeProperties(theme: SharingTheme | null | undefined): Record<string, string>;
+export declare function applyTheme<E extends { style: CSSStyleDeclaration }>(el: E, theme: SharingTheme | null | undefined): E;
+
+/** What an app's own UI receives: show its own sheet with `copy`, then answer from the learner's tap. */
+export interface OwnAsk extends Ask { lang: string; copy: Deck; consentVersion: string }
 export declare function registerDeck(lang: string, deck: { format: 'quranlab.sharing-copy/1'; [k: string]: unknown }): void;
 export declare function languages(): string[];
 
 export interface SharingController {
   lang: string;
   state: SharingState;
-  deck: Deck;
+  /** the copy with the app's own wording applied (the same as copy) */
+  readonly deck: Deck;
+  readonly copy: Deck;
+  /** the consent a new grant records; send textSha256 or canonicalText to Quran Lab for a review of your wording */
+  readonly consent: Consent;
+  readonly wording: Readonly<Wording>;
+  readonly theme: SharingTheme | null;
+  /** replace deck strings (null or {} restores the deck); a TypeError for a bad key or text, nothing changes then */
+  setWording(wording: Wording | null): Consent;
+  setTheme(theme: SharingTheme | null): void;
+  /** the ask an app's own UI has not answered yet */
+  readonly pendingAsk: OwnAsk | null;
+  /** the learner's answer, from their own tap (default sheet and own UI); after a yes or a switch turned off it changes nothing */
+  answer(yes: boolean, o?: { guardianConfirmed?: boolean }): 'granted' | 'declined' | 'final';
   sessionCompleted(o?: { feedback?: boolean }): Promise<Answer | null>;
   setSharing(on: boolean, o?: { guardianConfirmed?: boolean }): void;
   /** "Delete what I shared": signed with this install's device key (no app credential can delete) */
@@ -50,15 +112,16 @@ export interface SharingController {
   impactLine(): Promise<string | null>;
 }
 
-/** Turn on the sharing experience for a configured client (contributions: true). */
-export declare function enableSharing(ql: QuranLab, o?: { lang?: string; ask?: 'auto' | ((a: Ask) => Promise<Answer>); idle?: () => boolean }): SharingController;
+/** Wire the sharing experience for a configured client (the SDK also does it when a model attaches in a page). */
+export declare function enableSharing(ql: QuranLab, o?: { lang?: string; ask?: 'auto' | ((a: OwnAsk) => Promise<Answer | null | void>); idle?: () => boolean;
+  wording?: Wording | null; theme?: SharingTheme | null }): SharingController;
 export declare function deleteWithKey(ql: QuranLab, key: import('../platform/index.js').ContributorKey): Promise<{ accepted: boolean; sessionsLeft: number | null }>;
 
 /** The web components (import '@quran-lab/tajweedformer/consent/element' or let enableSharing load them). */
 export declare class QuranLabConsent extends HTMLElement {
-  static ask(o?: { lang?: string; variant?: AskVariant; guardian?: boolean; parent?: Element }): Promise<{ yes: boolean; guardianConfirmed: boolean }>;
-  static thank(o?: { lang?: string; parent?: Element; ms?: number }): HTMLElement;
-  show(o?: { lang?: string; variant?: AskVariant; guardian?: boolean }): Promise<{ yes: boolean; guardianConfirmed: boolean }>;
+  static ask(o?: { lang?: string; variant?: AskVariant; guardian?: boolean; parent?: Element; wording?: Wording | null; theme?: SharingTheme | null }): Promise<{ yes: boolean; guardianConfirmed: boolean }>;
+  static thank(o?: { lang?: string; parent?: Element; ms?: number; wording?: Wording | null; theme?: SharingTheme | null }): HTMLElement;
+  show(o?: { lang?: string; variant?: AskVariant; guardian?: boolean; wording?: Wording | null; theme?: SharingTheme | null }): Promise<{ yes: boolean; guardianConfirmed: boolean }>;
 }
 export declare class QuranLabSharingSettings extends HTMLElement {
   controller: SharingController;

package/web/consent/index.js

@@ -5,45 +5,114 @@
 //
 //   import { QuranLab } from '@quran-lab/tajweedformer/platform';
 //   import { enableSharing } from '@quran-lab/tajweedformer/consent';
-//   const ql = await QuranLab.configure({ key, contributions: true });
-//   const sharing = enableSharing(ql, { lang: 'ar' });     // asks by itself after a session with feedback
+//   const ql = await QuranLab.configure({ key });
+//   const sharing = enableSharing(ql, { lang: 'ar' });     // asks by itself after a session with feedback, where
+//                                                          // the signed config offers sharing (flags.contributions)
 //   document.querySelector('quranlab-sharing-settings').controller = sharing;
+//
+// Since 2.0.1 the sheets take a theme (`theme`, or CSS custom properties), an app can show its own UI
+// (`ask: fn`, then the learner's answer through the return value or `sharing.answer(yes)`), and an app can
+// replace strings with its own wording (`wording`, `sharing.setWording`): a learner who agrees then agrees to that
+// text, under the version `custom-<24 hex>` derived from it, and each session sends its hash.
+//
+// The sheet is shown at most three times per install; a yes is kept, with the version the learner agreed to, across
+// copy decks, wordings and SDK upgrades (also from 2.0.0), and is never asked about again.
 
 import { SharingState } from './state.js';
 import { copyFor, registerDeck, languages, EN } from './copy.js';
+import { validateWording, deriveConsent } from './wording.js';
+import { themeProperties } from './theme.js';
 import { contributorKey, forgetContributorKey, deletionMessage, b64url, newRecoveryCode, recoveryHash } from '../platform/contributor-key.js';
+import { SDK_VERSION } from '../platform/client.js';
 
-export { SharingState, MAX_ASKS, REASK_GAP } from './state.js';
+export { SharingState, MAX_ASKS, REASK_GAP, LEGACY_CONSENT_VERSION, SHARING_STATE_KEY } from './state.js';
 export { copyFor, registerDeck, languages, EN } from './copy.js';
+export { validateWording, deriveConsent, canonicalConsentText, wordingKeys, sha256HexSync, CONSENT_TEXT_FORMAT, PLURAL_CATEGORIES } from './wording.js';
+export { THEME_PROPERTIES, themeProperties, applyTheme } from './theme.js';
 
 /**
  * Turn on the sharing experience for a configured platform client.
- * @param {import('../platform/client.js').QuranLab} ql  configured with contributions: true
+ * @param {import('../platform/client.js').QuranLab} ql  a configured client (the signed config decides whether sharing is offered)
  * @param {object} [o]
  * @param {string} [o.lang]  the deck's language (default: the browser's)
- * @param {'auto'|((ask: object) => Promise<{yes: boolean, guardianConfirmed?: boolean}>)} [o.ask='auto']
+ * @param {'auto'|((ask: object) => Promise<{yes: boolean, guardianConfirmed?: boolean}|null|undefined>)} [o.ask='auto']
  *        auto: the SDK shows <quranlab-consent> when the app is idle after a session with feedback; a
- *        function: the app shows it itself (timing only; the lines are copyFor(lang))
+ *        function: the app shows its own UI with the SDK's strings (`ask.copy`, the copy with any own wording)
+ *        and resolves with the learner's answer, or resolves with nothing and calls `sharing.answer(yes)` from
+ *        the learner's tap later. Counted and re-asked exactly like the SDK's own sheet (three asks at most).
  * @param {(() => boolean)} [o.idle]  whether the app is idle now (default: always)
+ * @param {Record<string, string>|null} [o.wording]  the app's own wording, {deck key: text} (see setWording)
+ * @param {object|null} [o.theme]  colours, corner radius and fonts of the SDK's sheets (THEME_PROPERTIES)
  */
 export function enableSharing(ql, o = {}) {
   const lang = o.lang || (globalThis.navigator && navigator.language) || 'en';
-  const deck = copyFor(lang);
-  const state = new SharingState(ql.state, { enabled: () => ql.sharingAllowed(), consentVersion: deck.consentVersion, audience: ql.audience });
+  let wording = validateWording(o.wording);
+  let theme = o.theme || null;
+  themeProperties(theme); // refuses a bad theme now, not when a sheet opens
+  let deck = copyFor(lang, wording);
+  let consent = deriveConsent(deck.consentVersion, wording);
+  const state = new SharingState(ql.state, { enabled: () => ql.sharingAllowed(), consentVersion: consent.version,
+    consentTextSha256: consent.textSha256, audience: ql.audience });
+  const count = (field) => { try { if (ql.telemetry && typeof ql.telemetry.count === 'function') ql.telemetry.count(field); } catch (_) { /* never in the way */ } };
+  let pending = null; // the ask an app's own UI has not answered yet
   const ctl = {
-    lang, state, deck,
+    lang, state,
+    /** The copy the sheets show and an app's own UI should show: the deck with the app's own wording applied. */
+    get deck() { return deck; },
+    get copy() { return deck; },
+    /** The consent a new grant records: { version, textSha256, canonicalText } (the last two null for the deck's own
+     * wording). Send textSha256 or canonicalText to Quran Lab for a review of your wording. */
+    get consent() { return consent; },
+    get wording() { return wording; },
+    get theme() { return theme; },
+    /**
+     * Replace deck strings with the app's own wording ({key: text}; plural lines as `impact.minutes.one`, ...;
+     * null or {} goes back to the deck). An unknown key or an empty or blank text throws a TypeError and nothing
+     * changes. A learner who agrees from now on agrees to this wording (its custom version); a learner who already
+     * agreed keeps the version recorded then, keeps sharing and is not asked again.
+     */
+    setWording(next) {
+      const w = validateWording(next);
+      wording = w;
+      deck = copyFor(lang, wording);
+      consent = deriveConsent(deck.consentVersion, wording);
+      state.setConsent(consent.version, consent.textSha256);
+      return consent;
+    },
+    /** The look of the SDK's sheets: { accent, accentText, background, text, secondaryText, cornerRadius, titleFont,
+     * bodyFont } (CSS values; null for the default). The words and the consent version do not change. */
+    setTheme(next) { themeProperties(next); theme = next || null; },
+    /** The ask an app's own UI is showing and has not answered (null when none). */
+    get pendingAsk() { return pending; },
+    /**
+     * The learner's answer to a consent ask, from the learner's own tap (the SDK's sheet calls it, and so does an
+     * app's own UI). yes: share under the wording shown; no: not now. Counted as share_yes or share_no. After a yes
+     * or the switch turned off it changes nothing (and counts nothing): the settings switch decides then.
+     */
+    answer(yes, { guardianConfirmed = false } = {}) {
+      const was = state.s.consent;
+      const r = state.answer(!!yes, { guardianConfirmed: !!guardianConfirmed });
+      pending = null;
+      if (was !== 'granted' && was !== 'final') count(yes ? 'share_yes' : 'share_no');
+      return r;
+    },
     /** The ask to show after a session (null when none is due); auto mode shows it. */
     async sessionCompleted({ feedback = true } = {}) {
       const ask = state.sessionCompleted({ feedback });
       if (!ask) return null;
-      const show = typeof o.ask === 'function' ? o.ask : async (a) => {
+      const own = typeof o.ask === 'function';
+      const show = own ? o.ask : async (a) => {
         const { QuranLabConsent } = await import('./element.js');
-        return QuranLabConsent.ask({ lang, variant: a.variant, guardian: a.guardian });
+        return QuranLabConsent.ask({ lang, variant: a.variant, guardian: a.guardian, wording, theme });
       };
       const wait = () => new Promise((r) => { const tick = () => (!o.idle || o.idle() ? r() : setTimeout(tick, 1000)); tick(); });
       await wait();
-      const a = await show(ask);
-      state.answer(!!a.yes, { guardianConfirmed: !!a.guardianConfirmed });
+      const full = { ...ask, lang, copy: deck, consentVersion: consent.version };
+      pending = full;
+      count('share_asked');
+      const a = await show(full);
+      if (!a || typeof a.yes !== 'boolean') return null; // the app's own UI answers later with ctl.answer()
+      if (pending === full) ctl.answer(a.yes, { guardianConfirmed: !!a.guardianConfirmed });
       return a;
     },
     /** The settings switch: off stops uploads at once and deletes the unsent queue. */
@@ -75,7 +144,7 @@ export function enableSharing(ql, o = {}) {
     async impactLine() {
       const s = await ql.contributionSummary();
       if (!s || !s.you || !s.you.minutes) return null;
-      return deck.minutes(Math.floor(s.you.minutes));
+      return ctl.copy.minutes(Math.floor(s.you.minutes));
     },
   };
   ql.sharing = ctl;
@@ -87,11 +156,27 @@ export function enableSharing(ql, o = {}) {
       const key = await contributorKey(ql.contributor());
       let code = ql.state.get('sharing.recovery');
       if (!code) { code = newRecoveryCode(); ql.state.set('sharing.recovery', code); }
+      // 2.0.0 passed ql.token() (a string; the outbox wants {token, attested}, so every pass stopped at
+      // "no token"), the telemetry device ({class, os_major}; the session JSON wants {deviceClass,
+      // osMajor}, so every start threw "os_major undefined" and was reported as sharing_start:error),
+      // snake_case decode fields (dropped), a flags snapshot and no consent check in the outbox
+      const tokenProvider = async () => {
+        const token = await ql.token();
+        return { token, attested: !!(ql._token && ql._token.attested) };
+      };
+      tokenProvider.invalidate = async () => { ql._token = null; ql.state.set('token', null); };
+      const dev = ql.telemetry.device || {};
       session = await mod.createSharingSession({
-        api: ql.apiUrl, fetch: ql.fetch, tokenProvider: () => ql.token(), headers: ql.origin ? { origin: ql.origin } : {},
+        api: ql.apiUrl, fetch: ql.fetch, tokenProvider, headers: ql.origin ? { origin: ql.origin } : {},
         contributor: ql.contributor(), contributorKeyRaw: key.publicKeyRaw, recoveryHash: await recoveryHash(code), inputSampleRate: tf.sampleRate, inputRoute: 'unknown',
-        decodeInfo: { model_revision: ql.modelRevision || null, backend: 'exact', weights_sha256: null, sdk_version: '2.0.0' },
-        consentVersion: deck.consentVersion, device: ql.telemetry.device, flags: ql.flags,
+        decodeInfo: { modelRevision: ql.modelRevision || null, backend: 'exact', weightsSha256: null, sdkVersion: SDK_VERSION },
+        // the version the learner agreed to, as recorded then (not the deck or wording in force now) and, for an
+        // app's own wording, the hash of that text
+        consentVersion: state.grantVersion, consentTextSha256: state.grantTextSha256,
+        device: { deviceClass: dev.class || 'browser', osMajor: dev.os_major || 1 },
+        // read at every pass: the signed config in force now, and the learner's answer now (a withdrawal
+        // or a config that turned sharing off stops the next PUT, not only the next session)
+        flags: () => ql.flags, enabled: () => state.sharing,
         ...(ql.sharingBitrate ? { bitrate: ql.sharingBitrate } : {}),
       });
       ctl.outbox = mod.outbox || ctl.outbox;
@@ -105,7 +190,7 @@ export function enableSharing(ql, o = {}) {
     };
     s.finish = () => {
       const k = finish();
-      if (starting) begin().then((x) => x && x.finish()).then(() => { if (state.takeThanks() && typeof o.ask !== 'function') import('./element.js').then((m) => m.QuranLabConsent.thank({ lang })); });
+      if (starting) begin().then((x) => x && x.finish()).then(() => { if (state.takeThanks() && typeof o.ask !== 'function') import('./element.js').then((m) => m.QuranLabConsent.thank({ lang, wording, theme })); });
       starting = null;
       return k;
     };

package/web/consent/state.js

@@ -1,88 +1,150 @@
 // The sharing state machine: when to ask,
 // how often to re-ask, the guardian variant, settings, the thank-you. Plain JS, no DOM.
+//
+// Asking, since 2.0.1:
+// - the sheet is shown at most MAX_ASKS times per install, ever (the first ask and, after "Not now", re-asks
+//   REASK_GAP sessions apart); the count is of asks handed out (the SDK's sheet or an app's own UI), stored, and
+//   carried over from 2.0.0's `asks`;
+// - a yes ends asking for good: the grant keeps the consent version (and, for an app's own wording, the text hash)
+//   recorded when the learner agreed, across copy decks, wordings and SDK upgrades. There is no version re-ask
+//   and nothing pauses sharing when the wording in force changes;
+// - turning sharing off ends asking for good; only the settings switch (setSharing) turns it on or off then.
+//
+// Stored under SHARING_STATE_KEY, the same object 2.0.0 stored: { v: 1, consent: 'unknown' | 'granted' |
+// 'declined' | 'final', asks, lastAskSession, sessions, thanked, decidedAt, consentVersion, guardian } plus
+// consentTextSha256 (2.0.1). 2.0.0's `versionAsked` is left as it is and no longer read.
 
 export const SHARING_STATE_KEY = 'sharing.v1';
 const FRESH = { v: 1, consent: 'unknown', asks: 0, lastAskSession: 0, sessions: 0, thanked: false, decidedAt: null,
-  consentVersion: null, guardian: false };
-/** Asks in all: the first and at most two re-asks. */
+  consentVersion: null, consentTextSha256: null, guardian: false };
+/** Sheets shown in all, ever: the first ask and at most two re-asks after "Not now". */
 export const MAX_ASKS = 3;
 /** Sessions between asks. */
 export const REASK_GAP = 7;
+/** The consent version of the copy deck the web SDK 2.0.0 bundled: a 2.0.0 grant stored without a version was
+ * given to it. */
+export const LEGACY_CONSENT_VERSION = 'share-2026-11-07';
 
 export class SharingState {
   /**
    * @param {{ get(k): any, set(k, v): void }} state  persistence (per origin in browsers)
-   * @param {{ enabled: () => boolean, consentVersion?: string, audience?: string, clock?: () => number }} o
+   * @param {{ enabled: () => boolean, consentVersion?: string, consentTextSha256?: string|null, audience?: string,
+   *           clock?: () => number }} o  consentVersion: the version a new grant records (the deck's, or custom-...
+   *           for an app's own wording, with its text hash)
    */
   constructor(state, o = {}) {
     this.state = state;
     this.enabledFn = o.enabled || (() => false);
     this.consentVersion = o.consentVersion || null;
+    this.consentTextSha256 = o.consentTextSha256 || null;
     this.audience = o.audience || 'general';
     this.clock = o.clock || Date.now;
     this.listeners = new Set();
   }
-  get s() { return { ...FRESH, ...(this.state.get(SHARING_STATE_KEY) || {}) }; }
+  get s() {
+    const s = { ...FRESH, ...(this.state.get(SHARING_STATE_KEY) || {}) };
+    if (!Number.isFinite(s.asks) || s.asks < 0) s.asks = 0;
+    // a 2.0.0 grant without a version was given to the deck 2.0.0 bundled
+    if (s.consent === 'granted' && !s.consentVersion) { s.consentVersion = LEGACY_CONSENT_VERSION; s.consentTextSha256 = null; }
+    return s;
+  }
   _put(s) { this.state.set(SHARING_STATE_KEY, s); for (const f of this.listeners) f(s); }
   onChange(f) { this.listeners.add(f); return () => this.listeners.delete(f); }
+  _today() { return new Date(this.clock()).toISOString().slice(0, 10); }
 
-  /** Uploads may run: enabled by the app and the signed config, and the learner said yes (for the
-   * current consent version). */
+  /** Uploads may run: enabled by the app and the signed config, and the learner said yes (to whichever
+   * version: a grant is never paused by a newer deck or wording). */
   get sharing() {
-    const s = this.s;
-    return this.enabledFn() && s.consent === 'granted';
+    return this.enabledFn() && this.s.consent === 'granted';
   }
   get guardianVariant() { return this.audience === 'children'; }
 
+  /** Asking has not ended: no yes, not turned off, and fewer than MAX_ASKS sheets shown. */
+  get asking() {
+    const s = this.s;
+    return (s.consent === 'unknown' || s.consent === 'declined') && s.asks < MAX_ASKS;
+  }
+
+  /** The version a NEW grant records (an app changed its wording, or a new deck). A learner who already agreed
+   * keeps the version recorded then, keeps sharing and is not asked again. */
+  setConsent(version, textSha256 = null) {
+    this.consentVersion = version || null;
+    this.consentTextSha256 = textSha256 || null;
+    for (const f of this.listeners) f(this.s);
+  }
+
+  /** The consent version the current grant was given to (null when not granted): what each session of this
+   * grant sends as consent_version. */
+  get grantVersion() { const s = this.s; return s.consent === 'granted' ? s.consentVersion : null; }
+
+  /** The hash of the custom wording the current grant was given to (null for a deck's own wording, or when
+   * not sharing): what each session of this grant sends as consent_text_sha256. */
+  get grantTextSha256() {
+    if (!this.sharing) return null;
+    const s = this.s;
+    return s.consentVersion && s.consentVersion.startsWith('custom-') ? s.consentTextSha256 || null : null;
+  }
+
+  _ask(s) {
+    if (!(s.consent === 'unknown' || s.consent === 'declined') || s.asks >= MAX_ASKS) return null;
+    if (s.asks > 0 && s.sessions - s.lastAskSession < REASK_GAP) return null;
+    return s.consent === 'declined' ? 'reask' : 'first';
+  }
+
   /**
-   * A session ended. Returns null, or the ask to show: { variant: 'first' | 'reask' | 'version',
-   * guardian: boolean }. The caller shows the sheet and calls answer().
+   * A session ended. Returns null, or the ask to show: { variant: 'first' | 'reask', guardian: boolean }
+   * (counted as shown). The caller shows the sheet and calls answer().
    * @param {{ feedback: boolean }} o  feedback: the learner was shown the model's verdicts
    */
   sessionCompleted({ feedback = false } = {}) {
     const s = this.s;
     s.sessions += 1;
-    let ask = null;
-    if (this.enabledFn() && feedback) {
-      if (s.consent === 'unknown') ask = 'first';
-      else if (s.consent === 'declined' && s.asks < MAX_ASKS && s.sessions - s.lastAskSession >= REASK_GAP) ask = 'reask';
-      else if (s.consent === 'granted' && this.consentVersion && s.consentVersion && s.consentVersion !== this.consentVersion && !s.versionAsked) {
-        ask = 'version'; s.versionAsked = this.consentVersion;
-      }
-    }
-    if (ask) { s.asks += ask === 'version' ? 0 : 1; s.lastAskSession = s.sessions; }
+    const ask = this.enabledFn() && feedback ? this._ask(s) : null;
+    if (ask) { s.asks += 1; s.lastAskSession = s.sessions; }
     this._put(s);
     return ask ? { variant: ask, guardian: this.guardianVariant } : null;
   }
 
-  /** The app asks now (its own timing); the disclosure lines stay the SDK's. */
-  askNow() { return { variant: this.s.consent === 'unknown' ? 'first' : 'reask', guardian: this.guardianVariant }; }
+  /** The app asks now (its own timing; the disclosure lines stay the SDK's). Counted as shown; null once asking
+   * has ended (a yes, sharing turned off, or MAX_ASKS sheets shown). The REASK_GAP spacing is the app's to keep. */
+  askNow() {
+    const s = this.s;
+    if (!(s.consent === 'unknown' || s.consent === 'declined') || s.asks >= MAX_ASKS) return null;
+    const variant = s.consent === 'declined' ? 'reask' : 'first';
+    s.asks += 1; s.lastAskSession = s.sessions;
+    this._put(s);
+    return { variant, guardian: this.guardianVariant };
+  }
 
   /**
-   * The learner answered the sheet. yes: share; no (or dismissed): not now (final after the last ask).
-   * guardianConfirmed must be true for a yes in the guardian variant.
+   * The learner answered the sheet. yes: share, recording the version in force now; no (or dismissed): not now
+   * (final after the last ask). guardianConfirmed must be true for a yes in the guardian variant. After a yes or
+   * a switch turned off this changes nothing (the recorded grant stays as it is): use setSharing.
    */
   answer(yes, { guardianConfirmed = false } = {}) {
     const s = this.s;
+    if (s.consent === 'granted' || s.consent === 'final') return s.consent;
     if (yes) {
       if (this.guardianVariant && !guardianConfirmed) throw new Error('the guardian variant needs the parent or guardian confirmation');
-      Object.assign(s, { consent: 'granted', decidedAt: new Date(this.clock()).toISOString().slice(0, 10), consentVersion: this.consentVersion,
-        guardian: !!guardianConfirmed });
+      Object.assign(s, { consent: 'granted', decidedAt: this._today(), consentVersion: this.consentVersion,
+        consentTextSha256: this.consentTextSha256, guardian: !!guardianConfirmed });
     } else {
       s.consent = s.asks >= MAX_ASKS ? 'final' : 'declined';
-      s.decidedAt = new Date(this.clock()).toISOString().slice(0, 10);
+      s.decidedAt = this._today();
     }
     this._put(s);
     return s.consent;
   }
 
-  /** The settings switch. Off is final until the learner turns it on again here. */
+  /** The settings switch. On records the version in force now (an existing grant keeps its own). Off is final
+   * until the learner turns it on again here, and is never asked about again. */
   setSharing(on, { guardianConfirmed = false } = {}) {
     const s = this.s;
     if (on) {
+      if (s.consent === 'granted') return;
       if (this.guardianVariant && !guardianConfirmed) throw new Error('the guardian variant needs the parent or guardian confirmation');
-      Object.assign(s, { consent: 'granted', consentVersion: this.consentVersion, guardian: !!guardianConfirmed,
-        decidedAt: new Date(this.clock()).toISOString().slice(0, 10) });
+      Object.assign(s, { consent: 'granted', consentVersion: this.consentVersion, consentTextSha256: this.consentTextSha256,
+        guardian: !!guardianConfirmed, decidedAt: this._today() });
     } else {
       s.consent = 'final';
     }

package/web/consent/theme.js

@@ -0,0 +1,31 @@
+// The look of the SDK's sharing sheets (consent, guardian, thanks, settings): the same theme keys as the Swift
+// SDK's SharingTheme, set as CSS custom properties on each element (an app can also set the properties in its
+// own CSS). A theme changes colours, corner radius and fonts, never the words or the consent version.
+
+/** Theme key -> the CSS custom property it sets. */
+export const THEME_PROPERTIES = Object.freeze({
+  accent: '--ql-accent', accentText: '--ql-accent-fg', background: '--ql-bg', text: '--ql-fg', secondaryText: '--ql-muted',
+  cornerRadius: '--ql-radius', titleFont: '--ql-title-font', bodyFont: '--ql-font',
+});
+
+/** A theme as CSS custom properties ({ '--ql-accent': '#2a3b8f', ... }); a number cornerRadius is in px. An
+ * unknown key or a value that is not a plain CSS value throws a TypeError; null or {} is the default look. */
+export function themeProperties(theme) {
+  if (theme === null || theme === undefined) return {};
+  if (typeof theme !== 'object' || Array.isArray(theme)) throw new TypeError('theme: an object');
+  const out = {};
+  for (const [k, v] of Object.entries(theme)) {
+    if (!(k in THEME_PROPERTIES)) throw new TypeError(`theme: unknown key ${k} (${Object.keys(THEME_PROPERTIES).join(', ')})`);
+    if (v === null || v === undefined || v === '') continue;
+    if (k === 'cornerRadius' && typeof v === 'number') { out[THEME_PROPERTIES[k]] = `${v}px`; continue; }
+    if (typeof v !== 'string' || /[;{}<>]/.test(v)) throw new TypeError(`theme: ${k} must be a CSS value`);
+    out[THEME_PROPERTIES[k]] = v;
+  }
+  return out;
+}
+
+/** Sets a theme's properties on an element (its shadow tree inherits them). */
+export function applyTheme(el, theme) {
+  for (const [k, v] of Object.entries(themeProperties(theme))) el.style.setProperty(k, v);
+  return el;
+}