@quran-lab/tajweedformer 0.0.0-stage → 2.0.0

package/web/consent/index.d.ts

@@ -0,0 +1,65 @@
+// Types for @quran-lab/tajweedformer/consent: the recitation sharing experience (SHARING_EXPERIENCE.md).
+import type { QuranLab, StateStore } from '../platform/index.js';
+
+export type AskVariant = 'first' | 'reask' | 'version';
+export interface Ask { variant: AskVariant; guardian: boolean }
+export interface Answer { yes: boolean; guardianConfirmed?: boolean }
+
+export declare const MAX_ASKS: 3;
+export declare const REASK_GAP: 7;
+
+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 */
+  readonly sharing: boolean;
+  readonly guardianVariant: boolean;
+  /** a session ended; the ask due now, or null */
+  sessionCompleted(o?: { feedback?: boolean }): Ask | null;
+  askNow(): Ask;
+  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. */
+export interface Deck {
+  lang: string; dir: 'ltr' | 'rtl'; version: string; consentVersion: string; deleteDays: number;
+  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 */
+  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 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;
+  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>;
+}
+
+/** 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;
+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 }>;
+}
+export declare class QuranLabSharingSettings extends HTMLElement {
+  controller: SharingController;
+}

package/web/consent/index.js

@@ -0,0 +1,154 @@
+// 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, contributions: true });
+//   const sharing = enableSharing(ql, { lang: 'ar' });     // asks by itself after a session with feedback
+//   document.querySelector('quranlab-sharing-settings').controller = sharing;
+
+import { SharingState } from './state.js';
+import { copyFor, registerDeck, languages, EN } from './copy.js';
+import { contributorKey, forgetContributorKey, deletionMessage, b64url, newRecoveryCode, recoveryHash } from '../platform/contributor-key.js';
+
+export { SharingState, MAX_ASKS, REASK_GAP } from './state.js';
+export { copyFor, registerDeck, languages, EN } from './copy.js';
+
+/**
+ * Turn on the sharing experience for a configured platform client.
+ * @param {import('../platform/client.js').QuranLab} ql  configured with contributions: true
+ * @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']
+ *        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))
+ * @param {(() => boolean)} [o.idle]  whether the app is idle now (default: always)
+ */
+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 });
+  const ctl = {
+    lang, state, deck,
+    /** 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 { QuranLabConsent } = await import('./element.js');
+        return QuranLabConsent.ask({ lang, variant: a.variant, guardian: a.guardian });
+      };
+      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 });
+      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 deck.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); }
+      session = await mod.createSharingSession({
+        api: ql.apiUrl, fetch: ql.fetch, tokenProvider: () => ql.token(), 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,
+        ...(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 })); });
+      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';

package/web/consent/state.js

@@ -0,0 +1,100 @@
+// The sharing state machine: when to ask,
+// how often to re-ask, the guardian variant, settings, the thank-you. Plain JS, no DOM.
+
+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. */
+export const MAX_ASKS = 3;
+/** Sessions between asks. */
+export const REASK_GAP = 7;
+
+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
+   */
+  constructor(state, o = {}) {
+    this.state = state;
+    this.enabledFn = o.enabled || (() => false);
+    this.consentVersion = o.consentVersion || 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) || {}) }; }
+  _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); }
+
+  /** Uploads may run: enabled by the app and the signed config, and the learner said yes (for the
+   * current consent version). */
+  get sharing() {
+    const s = this.s;
+    return this.enabledFn() && s.consent === 'granted';
+  }
+  get guardianVariant() { return this.audience === 'children'; }
+
+  /**
+   * A session ended. Returns null, or the ask to show: { variant: 'first' | 'reask' | 'version',
+   * guardian: boolean }. 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; }
+    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 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.
+   */
+  answer(yes, { guardianConfirmed = false } = {}) {
+    const s = this.s;
+    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 });
+    } else {
+      s.consent = s.asks >= MAX_ASKS ? 'final' : 'declined';
+      s.decidedAt = new Date(this.clock()).toISOString().slice(0, 10);
+    }
+    this._put(s);
+    return s.consent;
+  }
+
+  /** The settings switch. Off is final until the learner turns it on again here. */
+  setSharing(on, { guardianConfirmed = false } = {}) {
+    const s = this.s;
+    if (on) {
+      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) });
+    } else {
+      s.consent = 'final';
+    }
+    this._put(s);
+  }
+
+  /** The thank-you is due (first shared session uploaded): returns true once. */
+  takeThanks() {
+    const s = this.s;
+    if (s.consent !== 'granted' || s.thanked) return false;
+    s.thanked = true;
+    this._put(s);
+    return true;
+  }
+}

package/web/index.d.ts

@@ -0,0 +1,4 @@
+// Type definitions for @quran-lab/tajweedformer: the V4 TajweedFormer API (SDK 2.0.0).
+export * from './tajweed/index.js';
+import { TajweedFormer } from './tajweed/index.js';
+export default TajweedFormer;

package/web/index.js

@@ -0,0 +1,10 @@
+// @quran-lab/tajweedformer: TajweedFormer V4 for browsers and Node. The exact engine in WebAssembly
+// (single thread, SIMD128; works everywhere with no special headers), the model delivery (shared
+// cache, resumable, hashed), the decoded and tajweed layers, and the Quran Lab platform client.
+//   import { TajweedFormer } from '@quran-lab/tajweedformer';
+import createTajweedFormer from '../dist/tajweedformer.mjs';
+import { bindTajweed } from './tajweed/tajweedformer.js';
+export * from './tajweed/index.js';
+
+export const TajweedFormer = bindTajweed(createTajweedFormer);
+export default TajweedFormer;