@chipmobilesdk/rn-notification 0.6.0 → 0.7.0

package/lib/module/recurrence/index.js

@@ -0,0 +1,208 @@
+"use strict";
+
+/**
+ * Series registration and the lookahead window.
+ *
+ * A caller declares a rule once. The package expands it inside a finite window
+ * and refreshes that window on its own, because only it knows when the horizon
+ * has moved — that is the one piece of recurrence knowledge the consumer does
+ * not have.
+ *
+ * Occurrences carry derived identifiers, so re-expanding a series recognises
+ * what it already scheduled instead of creating duplicates. That is what makes
+ * a window refresh with nothing to do cost zero platform operations.
+ *
+ * Occurrences are written through the shared `ScheduleWriter`, like every other
+ * consumer notification, so a repeating tone gets its stop marker and the
+ * platform ceiling is respected here too.
+ */
+
+import { partsInZone } from "../schedule/anchor.js";
+import { validateIdentifier } from "../schedule/validate-identifier.js";
+import { validateRequest } from "../schedule/index.js";
+import { createScheduleWriter } from "../schedule/writer.js";
+import { DIAGNOSTIC_CODES, NotificationError } from "../contract/errors.js";
+import { expand, occurrenceKey } from "./expand.js";
+import { guardAgainstClockChange } from "./clock-guard.js";
+import { listSeries as readLedger, readSeries, removeSeries, upsertSeries } from "../state/series-ledger.js";
+/** Builds the request for one occurrence from the series template. */
+function toRequest(rule, occurrence) {
+  return {
+    id: occurrence.id,
+    content: rule.template.content,
+    tone: rule.template.tone,
+    moment: {
+      at: occurrence.at,
+      anchoring: occurrence.anchoring
+    },
+    routing: rule.template.routing,
+    actions: rule.template.actions,
+    ownerTag: rule.template.ownerTag,
+    groupTag: rule.template.groupTag
+  };
+}
+const belongsTo = (entry, seriesId) => entry.seriesId === seriesId || entry.id.startsWith(`${seriesId}#`);
+
+/**
+ * The latest occurrence a ledger entry written before 0.4.0 had emitted. Those
+ * entries kept no key, so it is read back off the device: the last occurrence
+ * still pending is the last one emitted.
+ */
+function recoverLastEmittedKey(pending, anchoring, zone) {
+  if (pending.length === 0) return undefined;
+  const latest = Math.max(...pending.map(entry => entry.resolvedAt));
+  return occurrenceKey(partsInZone(latest, anchoring === 'absolute' ? 'UTC' : zone));
+}
+export function createRecurrence(deps) {
+  const emit = deps.emit ?? (() => {});
+  const writer = createScheduleWriter(deps.engine);
+
+  /**
+   * Validates the template as the request every occurrence will be, once, so
+   * a series is refused at registration for exactly what a direct schedule
+   * would be refused for — an undeclared tone, too many actions, an oversized
+   * routing payload — rather than failing later inside maintenance.
+   */
+  const validateTemplate = rule => validateRequest({
+    id: rule.id,
+    content: rule.template.content,
+    tone: rule.template.tone,
+    moment: {
+      at: deps.now(),
+      anchoring: rule.anchoring ?? 'wallClock'
+    },
+    routing: rule.template.routing,
+    actions: rule.template.actions,
+    ownerTag: rule.template.ownerTag,
+    groupTag: rule.template.groupTag
+  }, deps.resolveTone);
+  const toneFor = rule => {
+    const tone = deps.resolveTone(rule.template.tone);
+    if (tone === undefined) {
+      throw new NotificationError(DIAGNOSTIC_CODES.UNDECLARED_TONE, `Tone "${rule.template.tone}" was never declared in the package configuration.`, {
+        toneId: rule.template.tone,
+        seriesId: rule.id
+      });
+    }
+    return tone;
+  };
+
+  /** Expands and registers, scheduling only occurrences the device lacks. */
+  const materialize = async (rule, tone) => {
+    const now = deps.now();
+    const zone = deps.timeZone();
+    const previous = readSeries(deps.state, rule.id);
+    const pending = await deps.engine.getPending();
+    const ofSeries = pending.filter(entry => belongsTo(entry, rule.id));
+    const expansion = expand({
+      rule,
+      from: now,
+      lookahead: deps.lookahead,
+      timeZone: zone,
+      alreadyEmitted: previous?.emittedCount ?? 0,
+      lastEmittedKey: previous?.lastEmittedKey ?? (previous !== undefined ? recoverLastEmittedKey(ofSeries, rule.anchoring, zone) : undefined)
+    });
+    const guarded = guardAgainstClockChange({
+      occurrences: expansion.occurrences,
+      previousHorizon: previous?.expandedThrough,
+      now,
+      previousNow: previous?.at
+    });
+    if (guarded.discontinuity !== 'none') {
+      emit('CLOCK_DISCONTINUITY', `Device clock moved ${guarded.discontinuity}; ${guarded.suppressed} already-handled occurrence(s) were suppressed rather than re-delivered.`, {
+        direction: guarded.discontinuity,
+        suppressed: guarded.suppressed,
+        seriesId: rule.id
+      });
+    }
+    const wanted = new Set(guarded.occurrences.map(occurrence => occurrence.id));
+
+    // Upcoming entries of this series the expansion no longer produces: ones
+    // written under the instant-based identity before 0.4.0, or ones whose slot
+    // the rule no longer has. Left in place, each would fire beside its
+    // replacement. Entries already due are left alone — they may be firing now.
+    const stale = ofSeries.filter(entry => !wanted.has(entry.id) && entry.resolvedAt > now);
+    for (const entry of stale) {
+      await writer.cancel(entry.id);
+    }
+    const onDevice = new Set(ofSeries.filter(entry => !stale.includes(entry)).map(entry => entry.id));
+    const missing = guarded.occurrences.filter(occurrence => !onDevice.has(occurrence.id));
+
+    // The same ceiling reconciliation respects: soonest first, the rest
+    // registered by a later refresh once they move into range.
+    const room = Math.max(0, (await writer.capacity()) - (pending.length - stale.length));
+    const toSchedule = missing.slice(0, room);
+    if (toSchedule.length < missing.length) {
+      emit(DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING, `Series "${rule.id}" has ${missing.length - toSchedule.length} occurrence(s) beyond the platform ceiling; they are registered by a later window refresh.`, {
+        seriesId: rule.id,
+        dropped: missing.length - toSchedule.length
+      });
+    }
+    const approximate = !deps.canScheduleExactly();
+    for (const occurrence of toSchedule) {
+      await writer.write({
+        request: toRequest(rule, occurrence),
+        resolvedAt: occurrence.at,
+        tone,
+        // The zone the series was expanded against; absent for absolute series.
+        anchoringGeneration: occurrence.anchoring === 'absolute' ? undefined : zone,
+        approximate,
+        seriesId: rule.id
+      });
+    }
+
+    // Counted once, when first emitted — whether or not the ceiling let it on
+    // the device yet. Occurrences re-produced from an earlier expansion are not
+    // counted again.
+    const newlyEmitted = guarded.occurrences.filter(occurrence => !occurrence.previouslyEmitted);
+    const lastEmittedKey = newlyEmitted.length > 0 ? newlyEmitted[newlyEmitted.length - 1].key : previous?.lastEmittedKey;
+    upsertSeries(deps.state, rule, {
+      expandedThrough: expansion.expandedThrough,
+      emittedCount: (previous?.emittedCount ?? 0) + newlyEmitted.length,
+      exhausted: expansion.exhausted,
+      lastEmittedKey
+    }, now);
+    return {
+      seriesId: rule.id,
+      scheduled: toSchedule.length,
+      expandedThrough: expansion.expandedThrough,
+      exhausted: expansion.exhausted,
+      cancelled: stale.map(entry => entry.id)
+    };
+  };
+  return {
+    async registerSeries(rule) {
+      validateIdentifier(rule.id, 'seriesId');
+      return materialize(rule, validateTemplate(rule));
+    },
+    /** Re-expands a tracked series. Called by the window-refresh maintenance step. */
+    async refreshSeries(rule) {
+      return materialize(rule, toneFor(rule));
+    },
+    async cancelSeries(seriesId) {
+      validateIdentifier(seriesId, 'seriesId');
+
+      // Every occurrence already scheduled from this series goes, identified by
+      // its derived prefix rather than by a list the ledger would have to keep
+      // in sync with the device.
+      const pending = await deps.engine.getPending();
+      const ids = pending.filter(entry => belongsTo(entry, seriesId)).map(entry => entry.id);
+      await deps.engine.cancelMany(ids);
+      const pass = writer.pass();
+      for (const id of ids) await pass.releaseStop(id);
+      removeSeries(deps.state, seriesId);
+      return ids;
+    },
+    async listSeries() {
+      const pending = await deps.engine.getPending();
+      return readLedger(deps.state).map(entry => ({
+        seriesId: entry.seriesId,
+        anchoring: entry.anchoring,
+        expandedThrough: entry.expandedThrough,
+        pendingOccurrences: pending.filter(p => belongsTo(p, entry.seriesId)).length,
+        exhausted: entry.exhausted
+      }));
+    }
+  };
+}
+//# sourceMappingURL=index.js.map

package/lib/module/recurrence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["partsInZone","validateIdentifier","validateRequest","createScheduleWriter","DIAGNOSTIC_CODES","NotificationError","expand","occurrenceKey","guardAgainstClockChange","listSeries","readLedger","readSeries","removeSeries","upsertSeries","toRequest","rule","occurrence","id","content","template","tone","moment","at","anchoring","routing","actions","ownerTag","groupTag","belongsTo","entry","seriesId","startsWith","recoverLastEmittedKey","pending","zone","length","undefined","latest","Math","max","map","resolvedAt","createRecurrence","deps","emit","writer","engine","validateTemplate","now","resolveTone","toneFor","UNDECLARED_TONE","toneId","materialize","timeZone","previous","state","getPending","ofSeries","filter","expansion","from","lookahead","alreadyEmitted","emittedCount","lastEmittedKey","guarded","occurrences","previousHorizon","expandedThrough","previousNow","discontinuity","suppressed","direction","wanted","Set","stale","has","cancel","onDevice","includes","missing","room","capacity","toSchedule","slice","TRUNCATED_OVER_CEILING","dropped","approximate","canScheduleExactly","write","request","anchoringGeneration","newlyEmitted","previouslyEmitted","key","exhausted","scheduled","cancelled","registerSeries","refreshSeries","cancelSeries","ids","cancelMany","pass","releaseStop","pendingOccurrences","p"],"sourceRoot":"../../../src","sources":["recurrence/index.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/repeat/expiry.js

@@ -0,0 +1,37 @@
+"use strict";
+
+/**
+ * Repeat expiry.
+ *
+ * When a stop marker is delivered, the alert it guards has run its declared
+ * course. This handler ends the sound and leaves the notification exactly where
+ * it is, then removes the marker.
+ *
+ * Nothing here imports the engine. It talks to the port, which is what lets the
+ * whole mechanism be proven on a virtual clock with no device.
+ */
+
+import { createStopPlacement } from "./place.js";
+export function createRepeatExpiryHandler(deps) {
+  return {
+    async handle(event) {
+      const stop = event.repeatStop;
+      if (stop === undefined) return;
+
+      // Order matters. Silence first, remove the marker second: if the
+      // process dies between the two, a marker left behind is harmless
+      // noise, whereas a device left sounding is the failure this exists to
+      // prevent.
+      //
+      // `silenceDelivered` returning false is the ordinary case, not an
+      // error — it means the user already handled the notification. Checking
+      // the tray rather than racing to cancel the marker on interaction is
+      // what makes early handling correct by construction: even if the marker
+      // fires, there is nothing left to act on.
+      await deps.engine.silenceDelivered(stop.targetId);
+      await deps.engine.cancel(stop.markerId);
+    },
+    release: targetId => createStopPlacement(deps.engine).release(targetId)
+  };
+}
+//# sourceMappingURL=expiry.js.map

package/lib/module/repeat/expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createStopPlacement","createRepeatExpiryHandler","deps","handle","event","stop","repeatStop","undefined","engine","silenceDelivered","targetId","cancel","markerId","release"],"sourceRoot":"../../../src","sources":["repeat/expiry.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,mBAAmB,QAAQ,YAAS;AAc7C,OAAO,SAASC,yBAAyBA,CAACC,IAA8B,EAAuB;EAC9F,OAAO;IACN,MAAMC,MAAMA,CAACC,KAAoB,EAAiB;MACjD,MAAMC,IAAI,GAAGD,KAAK,CAACE,UAAU;MAC7B,IAAID,IAAI,KAAKE,SAAS,EAAE;;MAExB;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA,MAAML,IAAI,CAACM,MAAM,CAACC,gBAAgB,CAACJ,IAAI,CAACK,QAAQ,CAAC;MACjD,MAAMR,IAAI,CAACM,MAAM,CAACG,MAAM,CAACN,IAAI,CAACO,QAAQ,CAAC;IACxC,CAAC;IAEDC,OAAO,EAAEH,QAAQ,IAAIV,mBAAmB,CAACE,IAAI,CAACM,MAAM,CAAC,CAACK,OAAO,CAACH,QAAQ;EACvE,CAAC;AACF","ignoreList":[]}

package/lib/module/repeat/index.js

@@ -0,0 +1,67 @@
+"use strict";
+
+/**
+ * Repeat expiry — bounding an alert that repeats until it is handled.
+ *
+ * The one piece of this package a consumer has to wire up themselves. The
+ * engine registers its background task at module scope, outside the React tree,
+ * and no library can perform that registration on an app's behalf.
+ *
+ * An app that declares no repeating tone needs none of this.
+ */
+
+import { buffer } from "../state/interaction-buffer.js";
+import { StateManager } from "../state/record.js";
+import { createRepeatExpiryHandler } from "./expiry.js";
+export { createRepeatExpiryHandler } from "./expiry.js";
+export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from "./marker.js";
+/**
+ * Registers the handler that ends a repeating alert while the app is dead.
+ *
+ * Call this at module scope in `index.js`, beside the app registration — not
+ * inside a component, and not inside an effect. By the time a component mounts,
+ * the process that needed this handler has already been asked to run it.
+ *
+ * Without it a repeating alert still starts and still stops when the user
+ * handles it, but nothing ends it on a device left face-down on a table. That
+ * is the whole reason the feature exists, so `apply()` reports its absence
+ * rather than letting anyone find out the hard way.
+ */
+export function registerBackgroundNotificationHandler(registration) {
+  const handler = createRepeatExpiryHandler(registration);
+  const keep = event => {
+    if (registration.store === undefined) return;
+    // A manager of its own: this runs in a process with no runtime, and the
+    // runtime created later loads what is written here.
+    buffer(new StateManager({
+      store: registration.store,
+      now: registration.now ?? (() => Date.now())
+    }), event);
+  };
+  registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event), async event => {
+    if (registration.onInteraction === undefined) {
+      keep(event);
+      return;
+    }
+    try {
+      await registration.onInteraction(event);
+    } catch {
+      // The app's handler failed; the interaction is kept rather than lost.
+      keep(event);
+    }
+  });
+
+  // Both paths, not just the background one. The engine routes a delivery to
+  // the foreground listener while the app is alive and to the headless task
+  // only when it is not — so registering only the latter leaves the alert
+  // sounding for anyone holding the phone when the window runs out, which is
+  // the one case they would certainly notice.
+  registration.engine.subscribeToDeliveries(event => {
+    // Deliberately not awaited: the engine's foreground listener is
+    // synchronous, and a rejection here must not take the subscription down
+    // with it — a handler that stopped listening would leave every later
+    // alarm unbounded.
+    handler.handle(event).catch(() => {});
+  });
+}
+//# sourceMappingURL=index.js.map

package/lib/module/repeat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["buffer","StateManager","createRepeatExpiryHandler","REPEAT_STOP_PREFIX","isRepeatStopId","markerIdFor","repeatStopFor","registerBackgroundNotificationHandler","registration","handler","keep","event","store","undefined","now","Date","engine","registerBackgroundDeliveryHandler","handle","onInteraction","subscribeToDeliveries","catch"],"sourceRoot":"../../../src","sources":["repeat/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA,SAASA,MAAM,QAAQ,gCAA6B;AACpD,SAASC,YAAY,QAAQ,oBAAiB;AAE9C,SAASC,yBAAyB,QAAQ,aAAU;AAEpD,SAASA,yBAAyB,QAAQ,aAAU;AAEpD,SAASC,kBAAkB,EAAEC,cAAc,EAAEC,WAAW,EAAEC,aAAa,QAAQ,aAAU;AAuBzF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,qCAAqCA,CACpDC,YAA2C,EACpC;EACP,MAAMC,OAAO,GAAGP,yBAAyB,CAACM,YAAY,CAAC;EAEvD,MAAME,IAAI,GAAIC,KAAuB,IAAW;IAC/C,IAAIH,YAAY,CAACI,KAAK,KAAKC,SAAS,EAAE;IACtC;IACA;IACAb,MAAM,CACL,IAAIC,YAAY,CAAC;MAAEW,KAAK,EAAEJ,YAAY,CAACI,KAAK;MAAEE,GAAG,EAAEN,YAAY,CAACM,GAAG,KAAK,MAAMC,IAAI,CAACD,GAAG,CAAC,CAAC;IAAE,CAAC,CAAC,EAC5FH,KACD,CAAC;EACF,CAAC;EAEDH,YAAY,CAACQ,MAAM,CAACC,iCAAiC,CACpDN,KAAK,IAAIF,OAAO,CAACS,MAAM,CAACP,KAAK,CAAC,EAC9B,MAAMA,KAAK,IAAI;IACd,IAAIH,YAAY,CAACW,aAAa,KAAKN,SAAS,EAAE;MAC7CH,IAAI,CAACC,KAAK,CAAC;MACX;IACD;IACA,IAAI;MACH,MAAMH,YAAY,CAACW,aAAa,CAACR,KAAK,CAAC;IACxC,CAAC,CAAC,MAAM;MACP;MACAD,IAAI,CAACC,KAAK,CAAC;IACZ;EACD,CACD,CAAC;;EAED;EACA;EACA;EACA;EACA;EACAH,YAAY,CAACQ,MAAM,CAACI,qBAAqB,CAACT,KAAK,IAAI;IAClD;IACA;IACA;IACA;IACAF,OAAO,CAACS,MAAM,CAACP,KAAK,CAAC,CAACU,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;EACtC,CAAC,CAAC;AACH","ignoreList":[]}

package/lib/module/repeat/marker.js

@@ -0,0 +1,51 @@
+"use strict";
+
+/**
+ * Stop-marker identity.
+ *
+ * A repeating alert has to end without the app being alive, and no platform
+ * offers "stop the sound at time T but keep the notification". So the package
+ * schedules its own notification at T and reacts to its delivery. That
+ * notification is a *marker*: it exists to be delivered and immediately
+ * removed, never to be read.
+ *
+ * The marker's identifier is derived from the target's by hashing rather than by
+ * concatenation. Concatenation would overflow the package's 128-character
+ * identifier limit for any target already near it, and would make the marker's
+ * identity a function of a value the consumer controls — which is how a
+ * consumer identifier ends up colliding with an internal one.
+ */
+
+import { fnv1a, hex8 } from "../contract/hash.js";
+/**
+ * Reserved identifier namespace.
+ *
+ * Rejected as a consumer identifier prefix. A consumer id colliding with a
+ * marker would not merely confuse a listing: the expiry handler cancels
+ * markers, so the collision would delete a real notification.
+ */
+export const REPEAT_STOP_PREFIX = 'cms.stop:';
+
+/**
+ * The marker identifier for a target notification.
+ *
+ * Two independent hashes rather than one: a single 32-bit hash collides often
+ * enough to matter once a device holds a handful of alarms, and a collision here
+ * means one alarm's marker silences the other alarm and never silences its own.
+ */
+export function markerIdFor(targetId) {
+  return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
+}
+export function isRepeatStopId(id) {
+  return id.startsWith(REPEAT_STOP_PREFIX);
+}
+
+/** Describes the stop for a target whose alert must end at a known instant. */
+export function repeatStopFor(targetId, deliveredAt, forMs) {
+  return {
+    markerId: markerIdFor(targetId),
+    targetId,
+    dueAt: deliveredAt + forMs
+  };
+}
+//# sourceMappingURL=marker.js.map

package/lib/module/repeat/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["fnv1a","hex8","REPEAT_STOP_PREFIX","markerIdFor","targetId","isRepeatStopId","id","startsWith","repeatStopFor","deliveredAt","forMs","markerId","dueAt"],"sourceRoot":"../../../src","sources":["repeat/marker.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,KAAK,EAAEC,IAAI,QAAQ,qBAAkB;AAG9C;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,kBAAkB,GAAG,WAAW;;AAE7C;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAACC,QAAgB,EAAU;EACrD,OAAO,GAAGF,kBAAkB,GAAGD,IAAI,CAACD,KAAK,CAACI,QAAQ,EAAE,UAAU,CAAC,CAAC,GAAGH,IAAI,CAACD,KAAK,CAACI,QAAQ,EAAE,UAAU,CAAC,CAAC,EAAE;AACvG;AAEA,OAAO,SAASC,cAAcA,CAACC,EAAU,EAAW;EACnD,OAAOA,EAAE,CAACC,UAAU,CAACL,kBAAkB,CAAC;AACzC;;AAEA;AACA,OAAO,SAASM,aAAaA,CAACJ,QAAgB,EAAEK,WAAmB,EAAEC,KAAa,EAAc;EAC/F,OAAO;IACNC,QAAQ,EAAER,WAAW,CAACC,QAAQ,CAAC;IAC/BA,QAAQ;IACRQ,KAAK,EAAEH,WAAW,GAAGC;EACtB,CAAC;AACF","ignoreList":[]}

package/lib/module/repeat/place.js

@@ -0,0 +1,79 @@
+"use strict";
+
+/**
+ * Keeping a notification's stop marker in step with the notification.
+ *
+ * Shared by the scheduler and the reconciler rather than written twice. They are
+ * two doors into the same act — reconciliation is how most consumers schedule —
+ * and a bound that only existed on one path would be a bound that mostly did not
+ * exist.
+ */
+
+import { repeatStopFor } from "./marker.js";
+export function createStopPlacement(engine) {
+  /** `snapshot`: read once and kept current, for a pass; otherwise read on every call. */
+  function placement(snapshot) {
+    let known;
+
+    /** targetId → markerId of every outstanding stop. */
+    const outstanding = async () => {
+      if (snapshot && known) {
+        return known;
+      }
+      const read = new Map((await engine.listRepeatStops()).map(stop => [stop.targetId, stop.markerId]));
+      if (snapshot) {
+        known = read;
+      }
+      return read;
+    };
+    const release = async targetId => {
+      const stops = await outstanding();
+      const markerId = stops.get(targetId);
+      if (markerId !== undefined) {
+        await engine.cancel(markerId);
+        stops.delete(targetId);
+      }
+    };
+    return {
+      release,
+      async count() {
+        return (await outstanding()).size;
+      },
+      async sync(targetId, tone, deliversAt) {
+        await release(targetId);
+        const forMs = tone.android.repeatForMs;
+        if (!tone.android.loopSound || forMs === undefined) return;
+        const capabilities = await engine.getCapabilities();
+        if (!capabilities.supportsRepeatingAlert) return;
+        const stop = repeatStopFor(targetId, deliversAt, forMs);
+        await engine.schedule({
+          request: {
+            id: stop.markerId,
+            // Deliberately empty. A marker is delivered and removed within the
+            // same handler invocation; anything readable here would be text a
+            // user might glimpse and be confused by.
+            content: {
+              title: '',
+              body: ''
+            },
+            tone: tone.toneId,
+            // Absolute: the bound is a duration from a known instant, not a
+            // wall-clock time that should follow the user across time zones.
+            moment: {
+              at: stop.dueAt,
+              anchoring: 'absolute'
+            }
+          },
+          resolvedAt: stop.dueAt,
+          tone,
+          approximate: false,
+          repeatStop: stop
+        });
+        known?.set(targetId, stop.markerId);
+      },
+      pass: () => placement(true)
+    };
+  }
+  return placement(false);
+}
+//# sourceMappingURL=place.js.map

package/lib/module/repeat/place.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["repeatStopFor","createStopPlacement","engine","placement","snapshot","known","outstanding","read","Map","listRepeatStops","map","stop","targetId","markerId","release","stops","get","undefined","cancel","delete","count","size","sync","tone","deliversAt","forMs","android","repeatForMs","loopSound","capabilities","getCapabilities","supportsRepeatingAlert","schedule","request","id","content","title","body","toneId","moment","at","dueAt","anchoring","resolvedAt","approximate","repeatStop","set","pass"],"sourceRoot":"../../../src","sources":["repeat/place.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA,SAASA,aAAa,QAAQ,aAAU;AA8BxC,OAAO,SAASC,mBAAmBA,CAACC,MAAiC,EAAiB;EACrF;EACA,SAASC,SAASA,CAACC,QAAiB,EAAiB;IACpD,IAAIC,KAAsC;;IAE1C;IACA,MAAMC,WAAW,GAAG,MAAAA,CAAA,KAA0C;MAC7D,IAAIF,QAAQ,IAAIC,KAAK,EAAE;QACtB,OAAOA,KAAK;MACb;MACA,MAAME,IAAI,GAAG,IAAIC,GAAG,CACnB,CAAC,MAAMN,MAAM,CAACO,eAAe,CAAC,CAAC,EAAEC,GAAG,CAACC,IAAI,IAAI,CAACA,IAAI,CAACC,QAAQ,EAAED,IAAI,CAACE,QAAQ,CAAU,CACrF,CAAC;MACD,IAAIT,QAAQ,EAAE;QACbC,KAAK,GAAGE,IAAI;MACb;MACA,OAAOA,IAAI;IACZ,CAAC;IAED,MAAMO,OAAO,GAAG,MAAOF,QAAgB,IAAoB;MAC1D,MAAMG,KAAK,GAAG,MAAMT,WAAW,CAAC,CAAC;MACjC,MAAMO,QAAQ,GAAGE,KAAK,CAACC,GAAG,CAACJ,QAAQ,CAAC;MACpC,IAAIC,QAAQ,KAAKI,SAAS,EAAE;QAC3B,MAAMf,MAAM,CAACgB,MAAM,CAACL,QAAQ,CAAC;QAC7BE,KAAK,CAACI,MAAM,CAACP,QAAQ,CAAC;MACvB;IACD,CAAC;IAED,OAAO;MACNE,OAAO;MAEP,MAAMM,KAAKA,CAAA,EAAG;QACb,OAAO,CAAC,MAAMd,WAAW,CAAC,CAAC,EAAEe,IAAI;MAClC,CAAC;MAED,MAAMC,IAAIA,CAACV,QAAQ,EAAEW,IAAI,EAAEC,UAAU,EAAE;QACtC,MAAMV,OAAO,CAACF,QAAQ,CAAC;QAEvB,MAAMa,KAAK,GAAGF,IAAI,CAACG,OAAO,CAACC,WAAW;QACtC,IAAI,CAACJ,IAAI,CAACG,OAAO,CAACE,SAAS,IAAIH,KAAK,KAAKR,SAAS,EAAE;QAEpD,MAAMY,YAAY,GAAG,MAAM3B,MAAM,CAAC4B,eAAe,CAAC,CAAC;QACnD,IAAI,CAACD,YAAY,CAACE,sBAAsB,EAAE;QAE1C,MAAMpB,IAAI,GAAGX,aAAa,CAACY,QAAQ,EAAEY,UAAU,EAAEC,KAAK,CAAC;QACvD,MAAMvB,MAAM,CAAC8B,QAAQ,CAAC;UACrBC,OAAO,EAAE;YACRC,EAAE,EAAEvB,IAAI,CAACE,QAAQ;YACjB;YACA;YACA;YACAsB,OAAO,EAAE;cAAEC,KAAK,EAAE,EAAE;cAAEC,IAAI,EAAE;YAAG,CAAC;YAChCd,IAAI,EAAEA,IAAI,CAACe,MAAM;YACjB;YACA;YACAC,MAAM,EAAE;cAAEC,EAAE,EAAE7B,IAAI,CAAC8B,KAAK;cAAEC,SAAS,EAAE;YAAW;UACjD,CAAC;UACDC,UAAU,EAAEhC,IAAI,CAAC8B,KAAK;UACtBlB,IAAI;UACJqB,WAAW,EAAE,KAAK;UAClBC,UAAU,EAAElC;QACb,CAAC,CAAC;QACFN,KAAK,EAAEyC,GAAG,CAAClC,QAAQ,EAAED,IAAI,CAACE,QAAQ,CAAC;MACpC,CAAC;MAEDkC,IAAI,EAAEA,CAAA,KAAM5C,SAAS,CAAC,IAAI;IAC3B,CAAC;EACF;EAEA,OAAOA,SAAS,CAAC,KAAK,CAAC;AACxB","ignoreList":[]}