@quran-lab/tajweedformer 0.0.0-stage → 2.0.1

package/web/consent/element.js

@@ -0,0 +1,170 @@
+// <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 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, theme: { accent: '#0b6e4f' } });
+
+import { copyFor } from './copy.js';
+import { applyTheme } from './theme.js';
+
+const STYLE = `
+:host { all: initial; }
+dialog { box-sizing: border-box; max-inline-size: min(34rem, calc(100vw - 2rem)); inline-size: 100%; border: none;
+  max-block-size: calc(100dvh - 2rem); overflow: auto; overscroll-behavior: contain;
+  padding: 1.5rem; border-radius: var(--ql-radius, 16px); background: var(--ql-bg, #fdfcf8); color: var(--ql-fg, #1c1b19);
+  font: 400 1rem/1.55 var(--ql-font, system-ui, -apple-system, "Segoe UI", "Noto Sans", "Noto Naskh Arabic", sans-serif);
+  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; 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; }
+li { margin-block-end: .35rem; }
+label.guardian { display: flex; gap: .6rem; align-items: flex-start; margin: .5rem 0 1rem; font-weight: 600; }
+label.guardian input { inline-size: 1.2rem; block-size: 1.2rem; margin: .15rem 0 0; accent-color: var(--ql-accent, #2a3b8f); }
+.buttons { display: grid; grid-template-columns: 1fr 1fr; gap: .75rem; }
+@media (max-width: 420px) { .buttons { grid-template-columns: 1fr; } }
+button { font: inherit; font-weight: 600; min-block-size: 2.9rem; border-radius: calc(var(--ql-radius, 16px) * .6); cursor: pointer;
+  padding: .6rem 1rem; border: 2px solid var(--ql-accent, #2a3b8f); }
+button.primary { background: var(--ql-accent, #2a3b8f); color: var(--ql-accent-fg, #fff); }
+button.secondary { background: transparent; color: inherit; }
+button:disabled { opacity: .5; cursor: not-allowed; }
+button:focus-visible, input:focus-visible { outline: 3px solid var(--ql-accent, #2a3b8f); outline-offset: 2px; }
+.row { display: flex; justify-content: space-between; align-items: center; gap: 1rem; padding: .6rem 0; }
+.code { font-family: ui-monospace, monospace; font-size: .85rem; word-break: break-all; }
+@media (prefers-color-scheme: dark) {
+  dialog { background: var(--ql-bg, #1c1b19); color: var(--ql-fg, #f3f1ea); }
+  button { border-color: var(--ql-accent, #a9b6ff); }
+  button.primary { background: var(--ql-accent, #a9b6ff); color: var(--ql-accent-fg, #10142e); }
+  label.guardian input, button:focus-visible { accent-color: var(--ql-accent, #a9b6ff); outline-color: var(--ql-accent, #a9b6ff); }
+}
+h2:focus { outline: none; }
+`;
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+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,
+   *           wording?: Record<string, string>|null, theme?: object|null }} o
+   * @returns {Promise<{ yes: boolean, guardianConfirmed: boolean }>}
+   */
+  static ask(o = {}) {
+    const el = document.createElement('quranlab-consent');
+    (o.parent || document.body).appendChild(el);
+    return el.show(o).finally(() => el.remove());
+  }
+
+  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'])
+      .map((k) => `<li>${esc(t(k))}</li>`).join('');
+    const hadith = t('sheet.hadith') ? `<p class="muted">${esc(t('sheet.hadith'))}<br><small>${esc(t('sheet.hadith_ref'))}</small></p>` : '';
+    root.innerHTML = `<style>${STYLE}</style>
+<dialog part="sheet" lang="${esc(c.lang)}" dir="${esc(c.dir)}" aria-labelledby="t" aria-describedby="b">
+  <h2 id="t" part="title" tabindex="-1">${esc(t(guardian ? 'sheet.guardian.title' : 'sheet.title'))}</h2>
+  <div id="b" part="body">
+    ${guardian ? `<p part="guardian">${esc(t('sheet.guardian.body'))}</p>` : ''}
+    ${variant === 'reask' ? `<p>${esc(t('reask'))}</p>` : ''}
+    ${guardian ? '' : `<p>${esc(t('sheet.body'))}</p>`}
+    ${hadith}
+    <ul>${lines}</ul>
+  </div>
+  ${guardian ? `<label class="guardian"><input type="checkbox" id="g"> <span>${esc(t('sheet.guardian.confirm'))}</span></label>` : ''}
+  <div class="buttons">
+    <button class="primary" part="primary" id="yes" ${guardian ? 'disabled' : ''}>${esc(t(guardian ? 'sheet.guardian.share' : 'sheet.share'))}</button>
+    <button class="secondary" part="secondary" id="no">${esc(t('sheet.not_now'))}</button>
+  </div>
+</dialog>`;
+    const d = root.querySelector('dialog');
+    const g = root.querySelector('#g');
+    const yes = root.querySelector('#yes');
+    if (g) g.addEventListener('change', () => { yes.disabled = !g.checked; });
+    return new Promise((resolve) => {
+      let answered = false;
+      const done = (v) => { if (answered) return; answered = true; try { d.close(); } catch (_) { /* closed */ } resolve({ yes: v, guardianConfirmed: !!(g && g.checked) }); };
+      yes.addEventListener('click', () => done(true));
+      root.querySelector('#no').addEventListener('click', () => done(false));
+      d.addEventListener('close', () => done(false));
+      d.addEventListener('cancel', () => done(false));
+      if (typeof d.showModal === 'function') d.showModal(); else d.setAttribute('open', '');
+      // focus the title, not a button: neither choice is pre-selected
+      root.querySelector('#t').focus();
+    });
+  }
+
+  /** The one-time thank-you, as a small dismissable note. */
+  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: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;
+  }
+}
+
+/**
+ * <quranlab-sharing-settings>: the switch, "What is shared", "Delete what I shared" and the
+ * contribution code. Set `.controller` to the sharing controller (web/consent/index.js).
+ */
+export class QuranLabSharingSettings extends Base {
+  set controller(c) { this._c = c; this.render(); }
+  get controller() { return this._c; }
+  connectedCallback() { this.render(); }
+  render() {
+    if (!this._c) return;
+    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;
+    const code = this._c.recoveryCode();
+    root.innerHTML = `<style>${STYLE} :host{display:block} section{font:400 1rem/1.5 var(--ql-font,system-ui,sans-serif);color:inherit}</style>
+<section lang="${esc(c.lang)}" dir="${esc(c.dir)}">
+  <div class="row"><label for="s">${esc(t('settings.toggle'))}</label>
+    <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>${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>`;
+    const rc = root.querySelector('#rc');
+    // the code is put in the page only when the learner opens it, never in the initial markup
+    if (rc) rc.addEventListener('toggle', () => { root.querySelector('#code').textContent = rc.open ? this._c.recoveryCode() : ''; });
+    const msg = root.querySelector('#msg');
+    root.querySelector('#s').addEventListener('change', (e) => {
+      const g = root.querySelector('#g');
+      try { this._c.setSharing(e.target.checked, { guardianConfirmed: !!(g && g.checked) }); } catch (_) { e.target.checked = false; }
+      this.render();
+    });
+    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.failed.network');
+        if (ok) this.render();
+      }
+    });
+  }
+}
+
+if (globalThis.customElements && !globalThis.customElements.get('quranlab-consent')) {
+  globalThis.customElements.define('quranlab-consent', QuranLabConsent);
+  globalThis.customElements.define('quranlab-sharing-settings', QuranLabSharingSettings);
+}

package/web/consent/index.d.ts

@@ -0,0 +1,128 @@
+// 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; 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;
+  /** 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;
+  /** 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, 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: 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, 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;
+  /** 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) */
+  deleteShared(): Promise<{ accepted: boolean; sessionsLeft: number | null }>;
+  /** "Show my recovery code": for the learner only */
+  recoveryCode(): string | null;
+  rotateContributor(): Promise<void>;
+  impactLine(): Promise<string | null>;
+}
+
+/** 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; 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

@@ -0,0 +1,239 @@
+// Recitation sharing for the web product: the SDK's own consent sheet and settings (web components),
+// the state machine (when to ask, re-ask limits, guardian variant), and the wiring that shares the
+// WHOLE session while the SDK listens once the learner said yes (the 2.0.0 design; the upload itself is
+// web/sharing/, loaded lazily so it costs nothing until sharing is on).
+//
+//   import { QuranLab } from '@quran-lab/tajweedformer/platform';
+//   import { enableSharing } from '@quran-lab/tajweedformer/consent';
+//   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, 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  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}|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 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';
+  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,
+    /** 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 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, wording, theme });
+      };
+      const wait = () => new Promise((r) => { const tick = () => (!o.idle || o.idle() ? r() : setTimeout(tick, 1000)); tick(); });
+      await wait();
+      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. */
+    setSharing(on, opts) {
+      state.setSharing(on, opts);
+      if (!on && ctl.outbox) ctl.outbox.stop();
+    },
+    /** "Delete what I shared": challenge-response signed with this install's contributor key (P2.11). */
+    async deleteShared() {
+      const contributor = ql.contributor();
+      const key = await contributorKey(contributor, { create: false });
+      if (!key) { ql.resetContributor(); return { deleted: 0, objects: 0 }; } // never shared from here
+      const r = await deleteWithKey(ql, key);
+      await forgetContributorKey(contributor);
+      ql.resetContributor();
+      ql.state.set('sharing.recovery', null);
+      if (ctl.outbox) ctl.outbox.stop();
+      return r;
+    },
+    /** "Show my recovery code": for the learner's eyes only (call it from a confirm step in your UI). */
+    recoveryCode() { return ql.state.get('sharing.recovery'); },
+    /** A rejected contributor (403 contributor_revoked, 409 contributor_key_mismatch): new id, key, code. */
+    async rotateContributor() {
+      await forgetContributorKey(ql.contributor());
+      ql.resetContributor();
+      ql.state.set('sharing.recovery', null);
+    },
+    /** A quiet impact line from the backend's real numbers, or null. */
+    async impactLine() {
+      const s = await ql.contributionSummary();
+      if (!s || !s.you || !s.you.minutes) return null;
+      return ctl.copy.minutes(Math.floor(s.you.minutes));
+    },
+  };
+  ql.sharing = ctl;
+  // every session the SDK listens to, shared in full while consent is on (P2.9)
+  ctl.streamStarted = (tf, s) => {
+    if (!state.sharing) return;
+    let session = null, starting = null;
+    const begin = () => starting || (starting = import('../sharing/index.js').then(async (mod) => {
+      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, headers: ql.origin ? { origin: ql.origin } : {},
+        contributor: ql.contributor(), contributorKeyRaw: key.publicKeyRaw, recoveryHash: await recoveryHash(code), inputSampleRate: tf.sampleRate, inputRoute: 'unknown',
+        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;
+      return session;
+    }).catch((e) => { ql.reportIssue('other', 'sharing_start:' + (e.code || 'error')); return null; }));
+    const push = s.pushAudio, finish = s.finish, free = s.free;
+    s.pushAudio = (pcm) => {
+      const k = push(pcm);
+      if (state.sharing) { const copy = pcm.slice(); begin().then((x) => x && x.push(copy)); }
+      return k;
+    };
+    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, wording, theme })); });
+      starting = null;
+      return k;
+    };
+    s.free = () => { if (starting) begin().then((x) => x && x.finish()); starting = null; return free(); };
+  };
+  // the moment to ask: after a scored session (the learner saw feedback)
+  const scored = ql.scored.bind(ql);
+  ql.scored = (tf, r) => { scored(tf, r); ctl.sessionCompleted({ feedback: true }).catch(() => {}); };
+  return ctl;
+}
+
+/**
+ * "Delete what I shared" (PLATFORM_CLIENT.md section 9.1): a challenge for this app and contributor, the
+ * exact message signed with the device key (ECDSA P-256, SHA-256, r||s), then the deletion request. No
+ * app key or token is sent to these routes (the server refuses them). 202 is the answer whatever the
+ * signature (no enumeration); the summary then confirms. Returns { accepted, sessionsLeft }.
+ */
+export async function deleteWithKey(ql, key) {
+  const app = `${ql.platform}:${ql.bundleId}`;
+  const contributor = key.contributor;
+  const post = async (path, body) => {
+    const h = { 'content-type': 'application/json', ...(ql.origin ? { origin: ql.origin } : {}) };
+    const r = await ql.fetch(ql.apiUrl + path, { method: 'POST', headers: h, body: JSON.stringify(body) });
+    let j = {};
+    try { j = await r.json(); } catch (_) { /* none */ }
+    if (r.status >= 400) { const e = new Error(`${r.status} ${j.error || ''}`); e.status = r.status; e.code = j.error; throw e; }
+    return j;
+  };
+  let lastErr = null;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const { nonce } = await post('/v1/contributions/challenge', { app, contributor });
+    const timestamp = Math.floor(ql.clock() / 1000);
+    const sig = await key.sign(deletionMessage({ app, contributor, nonce, timestamp }));
+    try {
+      await post('/v1/contributions/delete', { app, contributor, nonce, timestamp, action: 'delete-all', signature: b64url(sig) });
+      const s = await ql.contributionSummary();
+      return { accepted: true, sessionsLeft: s && s.you ? s.you.sessions : null };
+    } catch (e) {
+      lastErr = e;
+      if (!(e.code === 'nonce_invalid' || e.code === 'timestamp_invalid')) throw e;
+    }
+  }
+  throw lastErr;
+}
+
+export { QuranLabConsent, QuranLabSharingSettings } from './element.js';