@vibes.diy/prompts 14.1.36 → 14.1.37

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 });
     }
@@ -983,6 +1010,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.37",
   "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.37",
+    "@vibes.diy/identity": "14.1.37",
+    "@vibes.diy/use-vibes-types": "14.1.37",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.3"
   },