@vibes.diy/prompts 14.1.36 → 14.1.38

package/llms/backend.md

@@ -149,7 +149,7 @@ const json = JSON.parse(
   await ctx.callAI("rate this", { schema: { properties: { verdict: { type: "string" }, score: { type: "number" } } } })
 ); // structured output
 const res = await ctx.fetch("https://api.example.com/x", { headers }); // outbound HTTP — use this, not bare fetch()
-await ctx.notify({ toHandle: "alice", body: "Your turn", dedupeKey: "game-7-turn-3" }); // one participant; throws on failure
+await ctx.notify({ toHandle: "alice", body: "Your turn", dedupeKey: "game-7-turn-3", path: "#game-7" }); // one participant; `path` optional; throws on failure
 ctx.log("info", "tick finished", { written: 3 }); // diagnostics — read back with: vibes-diy app logs owner/slug
 const gh = await ctx.github.fetch("/repos/acme/site/issues", { method: "POST", body: { title: "Filed from the vibe" } }); // connected GitHub repo
 ```
@@ -352,11 +352,11 @@ const gh = await ctx.github.fetch("/repos/acme/site/issues", { method: "POST", b
   Keep interactive/streaming AI in `App.jsx` via `callAI`; use `ctx.callAI`
   when the result must be server-authoritative (moderation, digests,
   summaries users shouldn't be able to forge).
-- **`ctx.notify({ toHandle, body, dedupeKey })` sends one person a notification.**
-  It takes a single object with all three fields — match the object form in the
-  example above, which is the calling convention (codegen has been observed
-  passing these positionally). The message lands in that person's bell, inbox,
-  and push notifications.
+- **`ctx.notify({ toHandle, body, dedupeKey, path })` sends one person a notification.**
+  It takes a single object; `toHandle`, `body` and `dedupeKey` are required and
+  `path` is optional — match the object form in the example above, which is the
+  calling convention (codegen has been observed passing these positionally).
+  The message lands in that person's bell, inbox, and push notifications.
   - `toHandle` is one handle, and the platform delivers to people already in
     this app: the owner, an accepted invite or approved request, or a handle
     named in the access function's persisted grant state.
@@ -366,6 +366,28 @@ const gh = await ctx.github.fetch("/repos/acme/site/issues", { method: "POST", b
   - `dedupeKey` names the happening, so one event delivers once however many
     times the handler runs: `"round-4-started"`, `"order-42-shipped"`,
     `"game-7-turn-3"`. The platform keys it per (app, recipient).
+  - `path` says WHERE in your app the notification points, so the bell and the
+    email land on the thing it is about instead of your front page. It must be
+    a `#` fragment — `"#game-7"`, `"#order/42"` — of at most 200 characters with
+    no spaces or line breaks, and nothing else: a fragment can only ever address
+    a position inside your own app, which is why it is the only form allowed.
+    Omit it and the notification links to the app itself, exactly as before.
+    **A malformed `path` fails the whole `ctx.notify` call** (the promise
+    rejects) rather than being quietly ignored — so a dead deep link is
+    something you find out about, not something your users find out about.
+  - Read it back in `App.jsx` from your own hash, and listen for changes,
+    because a click while the app is already open moves the hash without
+    reloading:
+
+    ```jsx
+    const [target, setTarget] = useState(() => window.location.hash.slice(1));
+    useEffect(() => {
+      const onHash = () => setTarget(window.location.hash.slice(1));
+      window.addEventListener("hashchange", onHash);
+      return () => window.removeEventListener("hashchange", onHash);
+    }, []);
+    // target === "game-7" → open that game
+    ```
   - `await` it and let it throw. Success resolves with nothing to inspect; a
     missing field, an over-long body, or a handle outside the app rejects the
     promise. Usually the surrounding work should survive an undeliverable
@@ -373,7 +395,12 @@ const gh = await ctx.github.fetch("/repos/acme/site/issues", { method: "POST", b
 
     ```js
     try {
-      await ctx.notify({ toHandle: game.opponent, body: "Your turn", dedupeKey: `game-${game._id}-turn-${game.turn}` });
+      await ctx.notify({
+        toHandle: game.opponent,
+        body: "Your turn",
+        dedupeKey: `game-${game._id}-turn-${game.turn}`,
+        path: `#game-${game._id}`, // lands them on THAT game, not the lobby
+      });
     } catch (err) {
       ctx.log("warn", "notify failed", { game: game._id, reason: err.message });
     }
@@ -815,6 +842,87 @@ And **only say a thing you computed.** "Tonight", "this morning", "in an hour"
 are claims about the reader's clock; if the code did not derive them from that
 reader's zone, name the moment instead and let them place it.
 
+### Recurring reminders on somebody's clock
+
+**A recurring reminder fires on each person's own clock, never the server's.**
+Once a reminder repeats — "every weekday at 7" — the zone stops being one
+setting on one schedule document and becomes a property of each person the
+reminder is for. Everything below is per person, and none of it is the
+server's day or the server's hour.
+
+**Capture the zone as an effect, not as a question.** Do not ask them for a
+timezone: the browser already knows it, so write it once when they first sign
+in and leave it alone. Store it where the reminder is addressed — on the
+person's own profile document when the list is shared — and guard the write so
+it only ever happens on a real change, or the effect re-fires forever.
+
+**Derive the weekday and the hour together, in that zone, from one
+`formatToParts` call.** `getUTCDay()`/`getUTCHours()` answer a question about
+the machine the handler happens to be running on; at 07:00 in Los Angeles it is
+already a different day in UTC, so a weekday gate on the server's clock silently
+drops Monday mornings and fires on Saturday ones.
+
+**An unrecognised zone string throws.** `Intl.DateTimeFormat` raises a
+`RangeError` on a zone it does not know, so in a loop over people the formatting
+goes in a `try` and a bad profile is skipped — one stale record must not stop
+everybody else's reminder.
+
+The unit of work is that person's local date (`en-CA` formats it as
+`YYYY-MM-DD`), keyed per person, per "A tick that repeats is not a run that
+repeats" above: the interval is only how often the handler wakes up.
+
+App.jsx — write the zone once, when they arrive:
+
+```jsx
+useEffect(() => {
+  if (!me?.userHandle) return;
+  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  if (!timeZone || myProfile?.timeZone === timeZone) return; // already stored — don't churn
+  database.put({ _id: `profile:${me.userHandle}`, type: "profile", userHandle: me.userHandle, timeZone });
+}, [me?.userHandle, myProfile?.timeZone]);
+```
+
+backend.js — evaluate each person in their own zone:
+
+```js
+export const config = { scheduled: { interval: "15m" } };
+const WEEKDAYS = new Set(["Mon", "Tue", "Wed", "Thu", "Fri"]);
+
+export async function scheduled(event, ctx) {
+  const at = new Date(event.scheduledTime);
+  const profiles = await ctx.db.query({ db: DB, field: "type", key: "profile", limit: 500 });
+  ctx.log("debug", "reminder tick", { profiles: profiles.length });
+
+  for (const profile of profiles) {
+    const { timeZone, userHandle } = profile;
+    if (!timeZone || !userHandle) continue;
+    let weekday, hour, dateKey;
+    try {
+      // One formatter, one zone: the weekday and the hour must agree about the day.
+      const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        weekday: "short",
+        hour: "2-digit",
+        hourCycle: "h23",
+      }).formatToParts(at);
+      weekday = parts.find((p) => p.type === "weekday")?.value;
+      hour = Number(parts.find((p) => p.type === "hour")?.value);
+      dateKey = new Intl.DateTimeFormat("en-CA", { timeZone }).format(at); // "2026-09-18", their day
+    } catch {
+      continue; // unrecognised zone on one profile — skip the person, not the tick
+    }
+    if (!WEEKDAYS.has(weekday) || hour !== 7) continue;
+
+    const id = `morningReminder:${userHandle}:${dateKey}`; // the unit of work, per person
+    if (await ctx.db.get(id, { db: DB })) continue; // this morning is already done
+    await ctx.db.put(
+      { _id: id, type: "morningReminder", ownerHandle: userHandle, date: dateKey, checkedAt: at.toISOString() },
+      { db: DB }
+    );
+  }
+}
+```
+
 ### An unattended tick reports what it did
 
 **An unattended tick earns its spend.** Nobody is watching a scheduled run, so
@@ -983,6 +1091,7 @@ export async function scheduled(event, ctx) {
       toHandle: ctx.appInfo.ownerHandle,
       body: "Your six jokes are drafted and ready for the show.",
       dedupeKey: `draft-${dayKey}`,
+      path: `#draft/${dayKey}`,
     });
   } catch (err) {
     // The day stays claimed: the owner sees what went wrong and is not billed twice for it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.1.36",
+  "version": "14.1.38",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -34,9 +34,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "14.1.36",
-    "@vibes.diy/identity": "14.1.36",
-    "@vibes.diy/use-vibes-types": "14.1.36",
+    "@vibes.diy/call-ai-v2": "14.1.38",
+    "@vibes.diy/identity": "14.1.38",
+    "@vibes.diy/use-vibes-types": "14.1.38",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.3"
   },