${body}
${this._renderReview()}
${this._renderRejectSheet()}
@@ -1019,6 +1048,15 @@ class TaskMateApprovalsCard extends LitElement {
const reject = () => this._handleRejectReward(it.id, it.title, it.childName);
return this._apActionPair(approve, reject, isLoading, shape);
}
+ if (it.kind === "owed") {
+ const done = () => this._handleRewardDelivered(it.id);
+ if (shape === "round") {
+ return html``;
+ }
+ return html``;
+ }
// mandatory miss: apply penalty (if any) / postpone / dismiss
if (shape === "round") {
return html`
@@ -1072,7 +1110,7 @@ class TaskMateApprovalsCard extends LitElement {
const photoUrl = this._photoHref(it.photo);
const ref = it.kind === "completion" ? it.reference : "";
if (it.kind !== "completion" || !(photoUrl || ref)) {
- return it.kind === "claim" && it.icon
+ return (it.kind === "claim" || it.kind === "owed") && it.icon
? html`${it.title}
- ${it.childName}${it.quantity ? html` · 🔢 ${it.quantity}` : ""}
+ ${it.childName}${it.quantity ? html` · 🔢 ${it.quantity}` : ""}${it.kind === "owed" ? html` · ${this._owedFor(it.daysOwed)}` : ""}
+${it.points}
+ ${it.kind === "owed" ? "" : "+"}${it.points}
${this._designActions(it, "full")}
@@ -1166,7 +1204,7 @@ class TaskMateApprovalsCard extends LitElement {
${this._av(it.childName, this._childAvatar(it.childId), tone, 34)}
${this._apPhotoDesigned(it, "ap-cn-photo")}
@@ -1184,10 +1222,10 @@ class TaskMateApprovalsCard extends LitElement {
${this._av(it.childName, this._childAvatar(it.childId), tone, 38)}
${this._apPhotoDesigned(it, "ap-cp-photo")}
- +${it.points}
+ ${it.kind === "owed" ? "" : "+"}${it.points}
`;
}
@@ -1299,6 +1337,67 @@ class TaskMateApprovalsCard extends LitElement {
}
}
+ // ---- reward fulfilment (#1098) ----------------------------------------
+ /** Redeemed rewards still to hand over, from either sensor, filtered like the claims. */
+ _owedRewards(entity, attrs) {
+ const list = (entity && entity.attributes && entity.attributes.owed_rewards) || attrs.owed_rewards || [];
+ return this._filterClaimsByChild(Array.isArray(list) ? list : []);
+ }
+
+ _owedFor(days) {
+ const n = Number(days) || 0;
+ if (n <= 0) return this._t('approvals.owed_today');
+ return this._t(n === 1 ? 'approvals.owed_days_one' : 'approvals.owed_days', { count: n });
+ }
+
+ _renderOwedRewards(owed) {
+ return html`
+ ${it.title}
- ${(it.childName || '').toUpperCase()} · +${it.points} XP${it.quantity ? html` · ${it.quantity}` : ""}
+ ${(it.childName || '').toUpperCase()} · ${it.kind === "owed" ? this._owedFor(it.daysOwed) : html`+${it.points} XP`}${it.quantity ? html` · ${it.quantity}` : ""}
${it.kind === "completion" ? this._renderStars(it.completion, "ap-cn-stars") : ""}
${it.title}
- ${it.childName}${time ? html` · ${time}` : ""}${it.quantity ? html` · 🔢 ${it.quantity}` : ""}
+ ${it.childName}${time ? html` · ${time}` : ""}${it.quantity ? html` · 🔢 ${it.quantity}` : ""}${it.kind === "owed" ? html` · ${this._owedFor(it.daysOwed)}` : ""}
${this._designActions(it, "ghost")}
+
+ `;
+ }
+
+ _renderOwedItem(o) {
+ const isLoading = this._loading[o.claim_id];
+ return html`
+
+
+ ${owed.map((o) => this._renderOwedItem(o))}
+
+
+ `;
+ }
+
+ async _handleRewardDelivered(claimId) {
+ await this._callClaimService('mark_reward_delivered', claimId);
+ }
+
// ---- mandatory-miss review (#532) ------------------------------------
_filterMissesByChild(misses) {
if (!this.config.child_id) return misses;
diff --git a/custom_components/taskmate/www/taskmate-child-card.js b/custom_components/taskmate/www/taskmate-child-card.js
index 83c21f50..308ecf74 100644
--- a/custom_components/taskmate/www/taskmate-child-card.js
+++ b/custom_components/taskmate/www/taskmate-child-card.js
@@ -103,6 +103,7 @@ class TaskMateChildCard extends LitElement {
|| this.hass?.states?.[this.config?.entity]?.attributes || {};
this._maybeBirthdayConfetti(attrs);
this._maybeInspectionCelebration(attrs);
+ this._maybeRecordConfetti(attrs);
this._scheduleUndoExpiry(attrs);
const sessions = attrs.active_timed_sessions || [];
const hasRunning = sessions.some(s => s.state === 'running' && s.child_id === this.config?.child_id);
@@ -1434,6 +1435,10 @@ class TaskMateChildCard extends LitElement {
.tm-care-sick { background: #e8f1ff; color: #1e3a6e; }
.tm-care-redeem { background: #fff4e0; color: #6b4200; }
.tm-care-goal { background: #ecf8ef; color: #1d5b2c; }
+ .tm-care-owed { background: #f3e9fb; color: #4a2070; }
+ .tm-care-owed .ic ha-icon { --mdc-icon-size: 26px; color: #8e44ad; }
+ .tm-care-owed .tm-owed-body { flex: 1; min-width: 0; }
+ .tm-care-record { background: #fff6d6; color: #6b4e00; }
.tm-care-goal.reached { background: #d9f5df; }
.tm-goal-set { cursor: pointer; width: 100%; }
.tm-goal-body { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 6px; }
@@ -5141,6 +5146,28 @@ class TaskMateChildCard extends LitElement {
🤝${this._t("child.redeem_title")}
+
+
+
+
+
+
+ ${this._t("child.redeem_body", { chore: offer.chore_name, points: offer.points, date: this._shortDate(offer.expires) })}`); } + // Reward fulfilment (#1098): what this child is still owed, with "Got it!". + for (const o of child.owed_rewards || []) { + const n = Number(o.days_owed) || 0; + const since = n <= 0 ? this._t("child.owed_today") : this._t(n === 1 ? "child.owed_days_one" : "child.owed_days", { count: n }); + parts.push(html`
+
${o.reward_name} · ${since} + +
`);
+ }
+ // Personal bests (#1099): records beaten today, for the rest of the day.
+ const bests = child.personal_bests;
+ if (bests && this.config.show_personal_bests !== false && Array.isArray(bests.new_today) && bests.new_today.length) {
+ const pointsName = this._pointsNameFor(child);
+ const lines = bests.new_today.map((key) => {
+ const rec = bests[key] || {};
+ return `${this._t(`child.record_${key}`, { points_name: pointsName })}: ${rec.value}`;
+ });
+ parts.push(html`${o.reward_name} · ${since} + +
+ 🏆${this._t("child.record_title")}
${lines.join(" · ")}
`);
+ }
const goal = child.weekly_goal;
if (goal && this.config.show_weekly_goal !== false) {
if (!goal.target) {
@@ -5163,6 +5190,44 @@ class TaskMateChildCard extends LitElement {
return html`${lines.join(" · ")}
${parts}
${this._renderGoalSheet()}`;
}
+ _pointsNameFor() {
+ const attrs = (window.__taskmate_attrs && window.__taskmate_attrs(this.hass, this.config?.entity))
+ || this.hass?.states?.[this.config?.entity]?.attributes || {};
+ return attrs.points_name || this._t("common.points");
+ }
+
+ async _gotReward(child, owed) {
+ const key = `owed_${owed.claim_id}`;
+ if (this._loading[key]) return;
+ this._loading = { ...this._loading, [key]: true };
+ this.requestUpdate();
+ try {
+ await this.hass.callService("taskmate", "mark_reward_delivered", { claim_id: owed.claim_id, child_id: child.id });
+ } catch (err) {
+ console.error("mark_reward_delivered failed", err);
+ } finally {
+ this._loading = { ...this._loading, [key]: false };
+ this.requestUpdate();
+ }
+ }
+
+ /* Personal bests (#1099): confetti the first time this device sees a record
+ beaten today — once per child, record and day, shared across cards. */
+ _maybeRecordConfetti(attrs) {
+ const child = (attrs.children || []).find(c => c.id === this.config?.child_id);
+ const fresh = child && child.personal_bests && child.personal_bests.new_today;
+ if (!Array.isArray(fresh) || !fresh.length || this.config?.show_personal_bests === false) return;
+ const KEY = "taskmate_records_celebrated";
+ let seen;
+ try { seen = JSON.parse(window.localStorage.getItem(KEY) || "[]") || []; } catch (e) { seen = []; }
+ if (!Array.isArray(seen)) seen = [];
+ const ids = fresh.map((k) => `${child.id}:${k}:${(child.personal_bests[k] || {}).date || ""}`).filter((id) => !seen.includes(id));
+ if (!ids.length) return;
+ seen.push(...ids);
+ try { window.localStorage.setItem(KEY, JSON.stringify(seen.slice(-60))); } catch (e) { /* private mode: plays each load */ }
+ this._spawnConfetti();
+ }
+
_shortDate(iso) {
const d = iso ? new Date(`${iso}T12:00:00`) : null;
if (!d || isNaN(d)) return iso || "";
@@ -5937,6 +6002,7 @@ class TaskMateChildCardEditor extends LitElement {
{ name: 'show_help_button', selector: { boolean: {} } },
{ name: 'show_mood', selector: { boolean: {} } },
{ name: 'show_weekly_goal', selector: { boolean: {} } },
+ { name: 'show_personal_bests', selector: { boolean: {} } },
{ name: 'show_description', selector: { boolean: {} } },
{ name: 'pre_reader', selector: { boolean: {} } },
{ name: 'pre_reader_labels', selector: { boolean: {} } },
@@ -5963,6 +6029,7 @@ class TaskMateChildCardEditor extends LitElement {
show_help_button: this._t('child.editor.show_help_button'),
show_mood: this._t('child.editor.show_mood'),
show_weekly_goal: this._t('child.editor.show_weekly_goal'),
+ show_personal_bests: this._t('child.editor.show_personal_bests'),
show_description: this._t('child.editor.show_description'),
pre_reader: this._t('child.editor.pre_reader'),
pre_reader_labels: this._t('child.editor.pre_reader_labels'),
@@ -6008,6 +6075,7 @@ class TaskMateChildCardEditor extends LitElement {
show_help_button: this.config.show_help_button !== false,
show_mood: this.config.show_mood !== false,
show_weekly_goal: this.config.show_weekly_goal !== false,
+ show_personal_bests: this.config.show_personal_bests !== false,
show_description: this.config.show_description === true,
pre_reader: this.config.pre_reader === true,
pre_reader_labels: this.config.pre_reader_labels === true,
@@ -6050,6 +6118,7 @@ class TaskMateChildCardEditor extends LitElement {
for (const [key, value] of Object.entries(newValues)) {
const defaults = {
show_countdown: true, show_minutes_left: true, show_help_button: true, show_mood: true, show_weekly_goal: true,
+ show_personal_bests: true,
show_description: false, debug: false,
time_category: 'morning', due_days_mode: 'hide',
recurrence_done_mode: 'dim', elapsed_time_mode: 'dim',
diff --git a/custom_components/taskmate/www/taskmate-panel.js b/custom_components/taskmate/www/taskmate-panel.js
index 3236af06..b6da4416 100644
--- a/custom_components/taskmate/www/taskmate-panel.js
+++ b/custom_components/taskmate/www/taskmate-panel.js
@@ -652,6 +652,7 @@ class TaskMatePanel extends HTMLElement {
if (act === "adjust-points") { this._doAdjustPoints(t.dataset.id, Number(t.dataset.delta)); return; }
if (act === "adjust-points-custom") { this._openAdjustDialog(t.dataset.id); return; }
if (act === "answer-help") { this._answerHelp(t.dataset.id); return; }
+ if (act === "reward-delivered") { this._markRewardDelivered(t.dataset.id); return; }
if (act === "toggle-sick") { this._toggleSickDay(t.dataset.id); return; }
if (act === "backdate-open") { this._openBackdateDialog(t.dataset.id); return; }
if (act === "save-backdate") { this._saveBackdateDialog(); return; }
@@ -4981,6 +4982,7 @@ class TaskMatePanel extends HTMLElement {
${this._renderHelpCard(kids)}
+ ${this._renderOwedCard(kids)}
`;
}
+ /** Reward fulfilment (#1098): redeemed rewards still to hand over, with a "Handed over" button each. */
+ _renderOwedCard(kids) {
+ const ids = new Set(kids.map(k => k.id));
+ const owed = (this._state.owed_rewards || []).filter(o => ids.has(o.child_id));
+ if (!owed.length) return "";
+ const names = Object.fromEntries((this._state.children || []).map(c => [c.id, c.name]));
+ const since = (o) => {
+ const n = Number(o.days_owed) || 0;
+ if (n <= 0) return this._t("panel.today_owed_today");
+ return this._t(n === 1 ? "panel.today_owed_days_one" : "panel.today_owed_days", { count: n });
+ };
+ return `
+
+
`;
+ }
+
+ async _markRewardDelivered(id) {
+ const { ok, err } = await this._callService("mark_reward_delivered", { claim_id: id });
+ if (!ok) { this._showToast("err", err); return; }
+ await this._fetchState();
+ this._showToast("ok", this._t("panel.today_owed_marked"));
+ }
+
async _answerHelp(id) {
const { ok, err } = await this._callService("answer_help", { request_id: id });
if (!ok) { this._showToast("err", err); return; }
@@ -9653,6 +9690,20 @@ class TaskMatePanel extends HTMLElement {
${this._t("panel.today_owed_title")} + ${owed.length}
+
+ ${owed.map(o => `
+
+
+
`).join("")}
+
+ ${this._esc(names[o.child_id] || o.child_name || "?")} — ${this._esc(o.reward_name || "")}
+
+
+
+
+
+
+
${this._t("panel.fulfilment_title")}
+
+
+
+ ${this._t("panel.fulfilment_enabled")}
+
+
+ ${this._t("panel.fulfilment_reminder_days")}${this._t("panel.fulfilment_reminder_days_hint")}
+
+ ${this._t("panel.allowance_title")}
@@ -14059,6 +14110,7 @@ class TaskMatePanel extends HTMLElement {
.tm-kid-sick-on { color: var(--info-color, #039be5); background: color-mix(in srgb, var(--info-color, #039be5) 14%, transparent); }
.tm-pill-info { background: color-mix(in srgb, var(--info-color, #039be5) 14%, transparent); color: var(--info-color, #039be5); }
.tm-help-card { border-inline-start: 4px solid var(--warning-color, #ffa600); }
+ .tm-owed-card { border-inline-start: 4px solid #8e44ad; }
.tm-help-list { display: flex; flex-direction: column; gap: 8px; }
.tm-help-row { display: flex; align-items: center; gap: 10px; justify-content: space-between; padding: 8px 0; border-top: 1px solid var(--divider-color); }
.tm-help-row:first-child { border-top: 0; }
diff --git a/custom_components/taskmate/www/taskmate-personal-bests-card.js b/custom_components/taskmate/www/taskmate-personal-bests-card.js
new file mode 100644
index 00000000..d2a15938
--- /dev/null
+++ b/custom_components/taskmate/www/taskmate-personal-bests-card.js
@@ -0,0 +1,467 @@
+/**
+ * TaskMate Personal Bests Card (#1099)
+ *
+ * A child's own records board: longest streak, most points in a day and in a
+ * week, most chores in a day and the biggest single award, each with the day
+ * it was set. A record beaten today glows for the rest of the day.
+ *
+ * Reads `children[].personal_bests` from the overview sensor. With a
+ * `child_id` it is that child's board; without one it shows every child.
+ */
+
+const LitElement = customElements.get("hui-masonry-view")
+ ? Object.getPrototypeOf(customElements.get("hui-masonry-view"))
+ : Object.getPrototypeOf(customElements.get("hui-view"));
+
+const html = LitElement.prototype.html;
+const css = LitElement.prototype.css;
+
+const _safeColor = (c, d) => (typeof c === "string" && /^#[0-9a-fA-F]{3,8}$/.test(c) ? c : d);
+
+const RECORDS = [
+ { key: "longest_streak", icon: "mdi:fire", emoji: "🔥" },
+ { key: "best_day_points", icon: "mdi:star-circle", emoji: "⭐" },
+ { key: "best_week_points", icon: "mdi:calendar-star", emoji: "📅" },
+ { key: "best_day_chores", icon: "mdi:check-all", emoji: "✅" },
+ { key: "best_single_award", icon: "mdi:trophy", emoji: "🏆" },
+];
+
+class TaskMatePersonalBestsCard extends LitElement {
+ static get properties() {
+ return {
+ hass: { type: Object },
+ config: { type: Object },
+ };
+ }
+
+ shouldUpdate(changedProps) {
+ if (changedProps.has("hass")) {
+ return window.__taskmate_hasChanged
+ ? window.__taskmate_hasChanged(changedProps.get("hass"), this.hass, this.config?.entity)
+ : true;
+ }
+ return true;
+ }
+
+ _t(key, params) {
+ const fn = window.__taskmate_localize;
+ return fn ? fn(this.hass, key, params) : key;
+ }
+
+ _avatarGlyph(source, fallback = "mdi:account-circle", cls = "pb-face-img") {
+ const face = window.__taskmate_child_visual(source);
+ return face.kind === "image"
+ ? html`
`
+ : html`
+
+
+ `;
+ }
+
+ _renderChild(child, pointsName) {
+ const tiles = this._tiles(child, pointsName);
+ const any = tiles.some(t => t.value != null);
+ return html`
+
+ ${this._designHeader(hd, 0)}
+
+ `;
+ }
+ if (entity.state === "unavailable" || entity.state === "unknown") {
+ return html`
+ ${this._designHeader(hd, 0)}
+
+ `;
+ }
+ const attrs = this._attrs(entity);
+ const children = this._children(attrs);
+ const pointsName = attrs.points_name || this._t("common.points");
+ const fresh = this._freshCount(children);
+ const body = children.length === 0
+ ? html`${this._designHeader(hd, fresh)} `;
+ }
+
+ _designChild(child, i, pointsName, design) {
+ const tone = this._designTone(i);
+ const tiles = this._tiles(child, pointsName);
+ const any = tiles.some(t => t.value != null);
+ const emoji = design === "playroom";
+ return html`
+ ` event, except the 1
| `taskmate_family_goal_reached_notification` † | Combined family points reached the goal |
| `taskmate_birthday`, `taskmate_presence_arrival`, `taskmate_item_rejected`, `taskmate_recap_ready`, `taskmate_bounty_claim_lapsing`, `taskmate_wish_requested`, `taskmate_inspection_reminder`, `taskmate_auction_closing`, `taskmate_auction_result` | (v6.0.0) The matching notification was dispatched |
| `taskmate_streak_freeze_used_notification` †, `taskmate_bounty_posted_notification` †, `taskmate_wish_pledged_notification` †, `taskmate_inspection_started_notification` †, `taskmate_inspection_passed_notification` †, `taskmate_auction_opened_notification` † | (v6.0.0) The matching notification was dispatched |
-| `taskmate_help_requested`, `taskmate_mood_low`, `taskmate_weekly_goal_reached`, `taskmate_penalty_redeemed`, `taskmate_raffle_drawn`, `taskmate_pet_evolved` | (v7.0.0) The matching notification was dispatched. These features have no separate event of their own, so automate on these. The per-child and family [event entities](Event-Entities.md) re-publish them too |
+| `taskmate_help_requested`, `taskmate_mood_low`, `taskmate_weekly_goal_reached`, `taskmate_penalty_redeemed`, `taskmate_raffle_drawn`, `taskmate_pet_evolved`, `taskmate_reward_owed` | (v7.0.0) The matching notification was dispatched. These features have no separate event of their own, so automate on these. The per-child and family [event entities](Event-Entities.md) re-publish them too |
| `taskmate_custom_notification` | Custom notification dispatched |
> **† Renamed in v6.1.0.** Before v6.1.0 these 11 notification events used the same name as the feature's own event, so an automation on, say, `taskmate_level_up` ran twice whenever the notification was sent. Now the feature event (no `recipients`, see [Automations](Automations.md)) fires once, and the notification event has the `_notification` suffix. If an automation reads `recipients` from one of these, trigger it on the `_notification` event. A `recipients is not defined` condition added to filter out the duplicate can be removed.
diff --git a/wiki/Personal-Bests.md b/wiki/Personal-Bests.md
new file mode 100644
index 00000000..c10e5cc3
--- /dev/null
+++ b/wiki/Personal-Bests.md
@@ -0,0 +1,100 @@
+# Personal Bests
+
+[Badges](Achievement-Badges.md) and [streak milestones](Bonus-Points.md) celebrate round numbers a parent chose. A **personal best** is the child's own bar: the most points they have ever earned in a day, their longest streak, their biggest single award. Beating one is celebrated whatever the number is, which is exactly what keeps a child who will never top the leaderboard trying.
+
+> **New in v7.1.0**
+
+Personal bests are always on. There is nothing to configure; the first chores set the baseline.
+
+---
+
+## The Records
+
+| Record | Key | What counts |
+|--------|-----|-------------|
+| **Longest streak** | `longest_streak` | The child's longest run of consecutive days with a chore done. Seeded from the streak history TaskMate already kept, so nobody starts from zero |
+| **Best day (points)** | `best_day_points` | Most points from approved chores in one day, bonus sub-tasks included |
+| **Most chores in a day** | `best_day_chores` | Most approved chores in one day (bonus sub-tasks don't count as chores) |
+| **Best week (points)** | `best_week_points` | Most points from approved chores in one Monday-to-Sunday week |
+| **Biggest award** | `best_single_award` | The most points one approval ever paid, multipliers included |
+
+Each record keeps the value and the day it was set.
+
+---
+
+## How Records Are Set
+
+Records are checked after every approval. The **first** time a measure is seen it is stored quietly as the baseline — a child's first chore is not "five records at once". From then on, going past a stored value is a new personal best:
+
+- the `taskmate_personal_best` event fires
+- the **Personal best** notification goes out, if switched on
+- a tier-2 [celebration](Celebrations.md) fires (`kind: personal_best`)
+- the child's card shows **New personal best!** naming the record, with confetti the first time that device sees it
+- the record glows as **New** on the Personal Bests card for the rest of the day
+
+Ties never re-celebrate. A record only moves when the number is bigger.
+
+### Undo and reject
+
+When an approval is undone or rejected, the day (or week) it belonged to is recomputed. A record that no longer holds falls back to the best the kept completion history can show, and stops being "new today". Records older than the kept history are left alone. The longest-streak record never goes down, matching the rest of TaskMate's streak handling.
+
+---
+
+## The Personal Bests Card
+
+
+
+```yaml
+type: custom:taskmate-personal-bests-card
+entity: sensor.taskmate_overview
+child_id: a8c8376a # optional — leave out to show every child
+title: My records # optional
+header_color: "#d35400"
+```
+
+One tile per record with the value and the day it was set. A record beaten today is marked **New** and shows what it beat. A child with no records yet gets *No records yet — the first chores set the bar*. Available in every [design style](Card-Design-Styles.md).
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `entity` | string | **required** | The TaskMate overview sensor |
+| `child_id` | string | _none_ | One child's board. Without it, every child gets a block |
+| `title` | string | `"Personal Bests"` | Card title |
+| `header_color` | string | `#d35400` | Header colour |
+| `card_design` | string | global default | Design style |
+
+### On the child card
+
+The child card announces today's new records in a banner above the chores. Switch it off per card with `show_personal_bests: false`.
+
+---
+
+## Notification
+
+| Type | Audience | Default |
+|------|----------|---------|
+| **Personal best** `personal_best` | Children and parents | Off |
+
+> 🏆 New personal best! Malia: most Stars in a day — 35.
+
+Turn it on under **TaskMate panel → Notifications**.
+
+---
+
+## Event
+
+`taskmate_personal_best` fires with `child_id`, `child_name`, `record` (one of the keys above), `value`, `previous`, `date` and `timestamp`. It shows as **Personal best** on the child's [event entity](Event-Entities.md). The matching notification's bus event is `taskmate_personal_best_notification`.
+
+---
+
+## Sensors
+
+Each child's entry in `sensor.taskmate_overview`'s `children` attribute carries `personal_bests` once there is a record: one object per record key with `value` and `date` (empty for a seeded streak), plus `previous` on a record beaten today and `new_today`, the list of record keys beaten today.
+
+---
+
+## Related
+
+- [Celebrations](Celebrations.md)
+- [Streak Freezes](Streak-Freezes.md) and [Bonus Points](Bonus-Points.md) — streak milestones
+- [Achievement Badges](Achievement-Badges.md)
+- [Insights](Insights.md)
diff --git a/wiki/Reward-Fulfilment.md b/wiki/Reward-Fulfilment.md
new file mode 100644
index 00000000..b53c8ec4
--- /dev/null
+++ b/wiki/Reward-Fulfilment.md
@@ -0,0 +1,87 @@
+# Reward Fulfilment
+
+Approving a reward spends the child's points. Until now that was the end of the story: nothing recorded whether the movie night actually happened or the Lego set ever arrived. **Reward fulfilment** keeps every approved reward on an **owed** list until somebody hands it over, shows the child what they are still due, and nags the parents when something has sat there too long.
+
+> **New in v7.1.0**
+
+---
+
+## Turning It On
+
+**TaskMate panel → Settings → Reward fulfilment**
+
+| Setting | Key | Default | Description |
+|---------|-----|---------|-------------|
+| **Track rewards until they are handed over** | `reward_fulfilment_enabled` | off | Approved rewards go on the owed list instead of disappearing into history |
+| **Remind me after** | `reward_fulfilment_reminder_days` | `3` | Days before parents get a push saying a reward is still owed, repeated every that many days while it stays owed. `0` = never remind (0–60) |
+
+Only rewards approved **while the tracker is on** are tracked. Turning it on does not back-fill old purchases, and turning it off hides the list without deleting anything.
+
+### What is never tracked
+
+- **Streak freezes** — TaskMate hands the token over itself the moment the claim is approved
+- **Timed unlocks** — the entity switches on by itself (see [Timed Unlock Rewards](Timed-Unlock-Rewards.md))
+- **Wishlist redemptions** — a [wish](Wishlist.md) already has its own hand-over step
+
+---
+
+## Handing a Reward Over
+
+Anywhere a parent approves rewards, the owed ones sit underneath with a **Handed over** button:
+
+- **Approvals card** — a *Still to hand over* section after the pending items, in every design style. Owed rewards never count towards the card's pending badge; they are not approvals.
+- **Admin panel → Today** — a *Rewards to hand over* card beside *Asked for help*, following the child filter.
+
+The child can also confirm for themselves: their card shows **You're owed a reward** with the reward, how long ago it was redeemed and a **Got it!** button. Tapping it marks the reward delivered by the child.
+
+Marking a reward delivered is final; there is no "un-deliver". If a parent taps by mistake, nothing is lost: the purchase is still in history, it just leaves the owed list.
+
+---
+
+## Reminders
+
+With the reminder set to *N* days, the parents receive the **Reward still owed** push the first time a reward has been owed for *N* days, then again every *N* days until it is handed over:
+
+> 🎁 Malia is still waiting for 'Movie night' — redeemed 3 days ago.
+
+The notification type `reward_owed` is **on by default** because it only ever fires once a parent has switched the tracker on. Route it or switch it off on the Notifications tab like any other type. It follows [multi-parent routing](Multi-Parent-Approval-Routing.md).
+
+---
+
+## Service
+
+| Service | Fields | Description |
+|---------|--------|-------------|
+| `taskmate.mark_reward_delivered` | `claim_id`, `child_id` (optional) | Mark an owed reward as handed over. Without `child_id` it is a parent action (an HA admin or a [TaskMate parent](Parent-Access.md); automations are allowed). With `child_id` it is the child confirming their own, through the same linked-child check as `complete_chore`, and the claim must belong to that child |
+
+```yaml
+action: taskmate.mark_reward_delivered
+data:
+ claim_id: 9c2f6d1e4a7b8c3d
+```
+
+Find the `claim_id` in the `owed_rewards` attribute of `sensor.taskmate_pending_approvals`, or in the `taskmate_reward_approved` event.
+
+---
+
+## Event
+
+Handing a reward over fires `taskmate_reward_delivered` with `child_id`, `child_name`, `reward_id`, `reward_name`, `claim_id`, `delivered_by` (`parent` or `child`) and `timestamp`. It shows as **Reward handed over** on the child's [event entity](Event-Entities.md).
+
+---
+
+## Sensors
+
+| Where | Attribute | Contents |
+|-------|-----------|----------|
+| `sensor.taskmate_pending_approvals` | `owed_rewards` | Every owed reward, oldest first: `claim_id`, `child_id`, `child_name`, `reward_id`, `reward_name`, `reward_icon`, `cost`, `approved_at`, `days_owed`. Present only while the tracker is on and something is owed |
+| `sensor.taskmate_overview` → `children[]` | `owed_rewards` | That child's owed rewards, compact: `claim_id`, `reward_name`, `reward_icon`, `days_owed`. Present only when there is one |
+
+---
+
+## Related
+
+- [Rewards](Rewards.md) — the rewards card and how claims work
+- [Managing Rewards](Managing-Rewards.md)
+- [Approvals Card](Approvals-Card.md)
+- [Notifications](Notifications.md)
diff --git a/wiki/Rewards.md b/wiki/Rewards.md
index 77ad4146..e7be287e 100644
--- a/wiki/Rewards.md
+++ b/wiki/Rewards.md
@@ -130,6 +130,7 @@ Restock only makes sense for rewards with a limited **Quantity**. See [Managing
## Related
+- [Reward Fulfilment](Reward-Fulfilment.md) — keep an approved reward on an owed list until it is handed over
- [Managing Rewards](Managing-Rewards.md) — create and edit rewards
- [Pool Mode (Savings Jars)](Pool-Mode-(Savings-Jars).md) — the savings-jar feature
- [Wishlist](Wishlist.md) — children save towards things they want, and the family can chip in
diff --git a/wiki/Sensor-Attributes.md b/wiki/Sensor-Attributes.md
index db07aacb..54958a0e 100644
--- a/wiki/Sensor-Attributes.md
+++ b/wiki/Sensor-Attributes.md
@@ -88,6 +88,8 @@ This is the main sensor. Its `extra_state_attributes` contain everything most ca
| `pet` | object | (v7.0.0) The child's [virtual pet](Virtual-Pets.md) (`adopted`, `name`, `species`, `stage`, `mood`, `xp`, `accessories`, …). Present only while pets are on |
| `weekly_goal` | object | (v7.0.0) The child's [weekly goal](Weekly-Goals.md) (`target`, `bonus`, `earned`, `reached`). Present only while weekly goals are on |
| `redemptions` | list | (v7.0.0) Open [make-it-right](Make-It-Right-Penalties.md) offers (`id`, `chore_id`, `chore_name`, `penalty_name`, `points`, `expires`). Present only when there is one |
+| `owed_rewards` | list | (v7.1.0) Redeemed rewards still to hand over (`claim_id`, `reward_name`, `reward_icon`, `days_owed`). Present only while [reward fulfilment](Reward-Fulfilment.md) is on and something is owed |
+| `personal_bests` | object | (v7.1.0) The child's [records](Personal-Bests.md): one object per record key (`value`, `date`, plus `previous` on a record beaten today) and `new_today`, the keys beaten today. Present once there is a record |
> Full field-by-field tables for `quests`, `challenges`, and `avatar_options` are in the [Sensor Reference](Sensor-Reference.md#children-array).
diff --git a/wiki/Sensor-Reference.md b/wiki/Sensor-Reference.md
index 68c10e2b..8374354e 100644
--- a/wiki/Sensor-Reference.md
+++ b/wiki/Sensor-Reference.md
@@ -101,6 +101,8 @@ Each entry in the `children` array:
| `pet` | object | (v7.0.0) The child's [virtual pet](Virtual-Pets.md), present only while pets are switched on. `{adopted: false}` before adoption; afterwards `adopted`, `name`, `species`, `stage` (`egg` / `baby` / `kid` / `teen` / `grown`), `chores` (since adoption), `xp` (growth), `mood` (`happy` / `proud` / `content` / `sleepy`), `accessories`, plus, when reached or switched on, `goal`, `legendary`, `home`, `pet_level`, `egg_ready` and `family` (earlier pets: `species`, `name`, `legendary`) |
| `weekly_goal` | object | (v7.0.0) The child's own [weekly goal](Weekly-Goals.md), present only while weekly goals are switched on: `target` (0 = not set), `bonus`, and once a target is set `earned` (points since Monday) and `reached` |
| `redemptions` | list | (v7.0.0) Open [make-it-right](Make-It-Right-Penalties.md) offers — each has `id`, `chore_id`, `chore_name`, `penalty_name`, `points` (what doing the chore gives back) and `expires` (ISO date, the last day it can be done). Present only when there is one |
+| `owed_rewards` | list | (v7.1.0) Redeemed rewards still to hand over, oldest first — each has `claim_id`, `reward_name`, `reward_icon` and `days_owed`. Present only while [reward fulfilment](Reward-Fulfilment.md) is switched on and something is owed |
+| `personal_bests` | object | (v7.1.0) The child's [personal bests](Personal-Bests.md), present once there is a record: for each of `longest_streak`, `best_day_points`, `best_day_chores`, `best_week_points`, `best_single_award` an object with `value` and `date` (ISO; empty for the seeded streak), plus `previous` when it was beaten today; and `new_today`, the list of record keys beaten today |
**`quests` entry fields:**
@@ -328,6 +330,7 @@ Numeric count of total pending items.
| `reward_claims` | list | Full details of pending reward claims |
| `mandatory_misses` | list | Unresolved mandatory-miss review items (see below). See [Mandatory Chores](Mandatory-Chores.md) |
| `quality_rating` | object | (v6.0.0) Present only while [quality ratings](Quality-Ratings.md) are on: `multipliers`, a list of the three star multipliers (★, ★★, ★★★). Approval cards use it to draw the star picker |
+| `owed_rewards` | list | (v7.1.0) Redeemed rewards still to hand over, oldest first: `claim_id`, `child_id`, `child_name`, `reward_id`, `reward_name`, `reward_icon`, `cost`, `approved_at`, `days_owed`. Present only while [reward fulfilment](Reward-Fulfilment.md) is on and something is owed |
**`chore_completions` entries:**
@@ -720,7 +723,7 @@ TaskMate's [bus events](Automations.md#bus-events-reference) are also published
| Entity | Description |
|--------|-------------|
-| `event.taskmate__activity` | One per child (friendly name ` activity`). Fires for that child's moments: `chore_completed`, `chore_approved`, `chore_rejected`, `chore_approval_undone`, `chore_auto_approved`, `reward_claimed`, `reward_approved`, `reward_rejected`, `badge_earned`, `level_up`, `streak_updated`, `streak_freeze_used`, `perfect_week`, `weekly_target_reached`, `weekly_goal_reached`, `quest_completed`, `challenge_completed`, `bonus_applied`, `penalty_applied`, `penalty_redeemed`, `surprise_bonus`, `mandatory_missed`, `team_chore_completed`, `points_gifted`, `help_requested`, `mood_logged`, `sick_day`, `raffle_won`, `pet_evolved` |
+| `event.taskmate__activity` | One per child (friendly name ` activity`). Fires for that child's moments: `chore_completed`, `chore_approved`, `chore_rejected`, `chore_approval_undone`, `chore_auto_approved`, `reward_claimed`, `reward_approved`, `reward_rejected`, `badge_earned`, `level_up`, `streak_updated`, `streak_freeze_used`, `perfect_week`, `weekly_target_reached`, `weekly_goal_reached`, `quest_completed`, `challenge_completed`, `bonus_applied`, `penalty_applied`, `penalty_redeemed`, `surprise_bonus`, `mandatory_missed`, `team_chore_completed`, `points_gifted`, `help_requested`, `mood_logged`, `sick_day`, `raffle_won`, `pet_evolved`, `reward_delivered`, `personal_best` |
| `event.taskmate_family_activity` | One for the family (friendly name `Family activity`). Fires for `family_goal_reached`, `season_champion`, `bounty_posted`, `scheduled_change_applied`, `raffle_drawn` |
The state is the time of the latest event; the `event_type` attribute says which one, and the event's own data (child, chore, points and so on) is copied onto the entity as attributes. A gift shows on both children's entities, and a teamwork chore on every team member's.
diff --git a/wiki/Services.md b/wiki/Services.md
index 2d8b8177..cbc9af6c 100644
--- a/wiki/Services.md
+++ b/wiki/Services.md
@@ -312,6 +312,16 @@ Approve a pending reward claim. For wallet rewards, deducts cost from the child'
| --- | --- | --- |
| `claim_id` | ✅ | ID of the pending reward claim |
+### `taskmate.mark_reward_delivered`
+(v7.1.0) An approved reward has been handed over, so it leaves the owed list. See [Reward Fulfilment](Reward-Fulfilment.md).
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `claim_id` | ✅ | The approved reward claim (from `owed_rewards` on `sensor.taskmate_pending_approvals`) |
+| `child_id` | ❌ | Give it when the child is confirming their own reward: the call then goes through the linked-child check and the claim must be theirs. Leave it out for a parent action |
+
+Refused for a claim that is not owed, or already marked delivered.
+
### `taskmate.reject_reward`
Reject a pending reward claim. For wallet rewards, no action (points were never deducted). For pool rewards, allocation stays in place — child can Redeem again.
diff --git a/wiki/images/personal-bests-card.png b/wiki/images/personal-bests-card.png
new file mode 100644
index 00000000..e1ce2909
Binary files /dev/null and b/wiki/images/personal-bests-card.png differ
diff --git a/wiki/index.md b/wiki/index.md
index 5f1ff94a..0fd869a2 100644
--- a/wiki/index.md
+++ b/wiki/index.md
@@ -97,6 +97,7 @@ Welcome to the TaskMate documentation. TaskMate is a Home Assistant integration
| [Recaps](Recaps.md) | A "Wrapped"-style story of each child's week, month or year |
| [Virtual Pets](Virtual-Pets.md) | A pet that hatches and grows as the child does chores |
| [Weekly Goals](Weekly-Goals.md) | Children set their own weekly points goal and earn a bonus for reaching it |
+| [Personal Bests](Personal-Bests.md) | Each child's own records — longest streak, best day, best week, biggest award — celebrated when beaten |
## Notifications & Admin
${this._t('common.entity_not_found', { entity: this.config.entity })}
${this._t('common.unavailable')}
+
+
+
+ ${fresh > 0 ? html`${this._t('bests.new_count', { count: fresh })}` : ""}
+
+ ${children.length === 0
+ ? html`
+ ${this._t('common.no_children')}
+
`;
+ }
+
+ /* ── designed (playroom / console / cleanpro / accessible / graphite) ── */
+
+ _designTone(i) { return `var(--tmd-c${(i % 6) + 1})`; }
+
+ _av(child, tone, size) {
+ const face = window.__taskmate_child_visual(child);
+ const inner = face.kind === "icon"
+ ? html`
+
+ ${this._avatarGlyph(child)}
+
+
+ ${child.name}
+ ${any ? this._t('bests.subtitle') : this._t('bests.none_yet')}
+
+ ${tiles.map((t) => html`
+
+
+
`)}
+ ${t.value == null ? "—" : t.value}
+ ${t.fresh && t.previous != null
+ ? this._t('bests.beat_previous', { previous: t.previous })
+ : (t.date || (t.value == null ? this._t('bests.not_yet') : ""))}
+ ${inner}
`;
+ }
+
+ _designHeader(hd, fresh) {
+ const title = this.config.title || this._t('bests.default_title');
+ return html`
+
+ 🏆
+ ${title}
+ ${fresh > 0 ? html`${this._t('bests.new_count', { count: fresh })}` : ""}
+
`;
+ }
+
+ _renderDesigned(design) {
+ const entity = this.hass.states[this.config.entity];
+ const hd = _safeColor(this.config.header_color, '#d35400');
+ if (!entity) {
+ return html`${this._t('common.entity_not_found', { entity: this.config.entity })}
${this._t('common.unavailable')}
${this._t('common.no_children')}
`
+ : children.map((child, i) => this._designChild(child, i, pointsName, design));
+ return html`${body}
+
`;
+ }
+}
+
+class TaskMatePersonalBestsCardEditor extends LitElement {
+ static get properties() {
+ return { hass: { type: Object }, config: { type: Object } };
+ }
+
+ _t(key, params) {
+ const fn = window.__taskmate_localize;
+ return fn ? fn(this.hass, key, params) : key;
+ }
+
+ setConfig(config) { this.config = config; }
+
+ _buildSchema() {
+ const entity = this.config?.entity ? this.hass?.states?.[this.config.entity] : null;
+ const children = entity?.attributes?.children || [];
+ return [
+ { name: 'entity', selector: { entity: { domain: 'sensor' } } },
+ { name: 'title', selector: { text: {} } },
+ {
+ name: 'child_id',
+ selector: {
+ select: {
+ options: [
+ { value: '__all__', label: this._t('common.editor.filter_by_child_all') },
+ ...children.map((c) => ({ value: c.id, label: c.name })),
+ ],
+ mode: 'dropdown',
+ },
+ },
+ },
+ {
+ name: 'card_design',
+ selector: {
+ select: {
+ options: window.__taskmate_design
+ ? window.__taskmate_design.editorOptions(this._t.bind(this))
+ : [{ value: 'global', label: 'Use global default' }],
+ mode: 'dropdown',
+ },
+ },
+ },
+ ];
+ }
+
+ _computeLabel = (entry) => {
+ const labels = {
+ show_adults: this._t('common.editor.show_adults'),
+ entity: this._t('common.editor.overview_entity'),
+ title: this._t('bests.editor.title'),
+ child_id: this._t('common.editor.filter_by_child'),
+ card_design: this._t('common.design.field_label'),
+ };
+ return labels[entry.name] ?? entry.name;
+ };
+
+ _computeHelper = (entry) => {
+ const helpers = {
+ show_adults: this._t('common.editor.show_adults_helper'),
+ entity: this._t('common.editor.overview_entity_helper'),
+ child_id: this._t('bests.editor.child_helper'),
+ };
+ return helpers[entry.name] ?? '';
+ };
+
+ render() {
+ if (!this.hass || !this.config) return html``;
+ const data = {
+ entity: this.config.entity || '',
+ title: this.config.title || '',
+ child_id: this.config.child_id || '__all__',
+ card_design: this.config.card_design || 'global',
+ };
+ return html`
+
+ ${this._av(child, tone, 34)}
+
+
+
+ ${child.name}
+ ${any ? this._t('bests.subtitle') : this._t('bests.none_yet')}
+
+ ${tiles.map((t) => html`
+
+
+
`)}
+ ${emoji ? html`${t.emoji} ` : html`
+ ${t.value == null ? "—" : t.value}
+ ${t.fresh && t.previous != null
+ ? this._t('bests.beat_previous', { previous: t.previous })
+ : (t.date || (t.value == null ? this._t('bests.not_yet') : ""))}
+