@vibes.diy/prompts 14.3.7 → 14.3.9

package/llms/backend.md

@@ -675,10 +675,24 @@ upstream that can be down, input that can be malformed — catches it and answer
 `{ ok: false, reason }` with a status the app can show, and the platform's 500
 stays the signal for a bug to fix.
 
+`/_api` opens to every caller once the app is published. Before its first
+publish, and after the owner unpublishes it, the routes answer the app's own
+people — its owner, its developers, and anyone it is shared with — and
+everyone else gets `404 backend.js _api: not found` without the handler
+running. The page reaches its own routes in every state through `apiFetch`
+(below), which arrives as the signed-in visitor. `call_own_api`, `onChange`
+and `scheduled` keep running, and a connected GitHub webhook runs until the
+owner unpublishes.
+
 ### Who is calling: `ctx.userInfo` comes from the request, never a cookie
 
-Cookies are not read. `ctx.userInfo` is filled in two ways:
+Cookies are not read. `ctx.userInfo` is filled in three ways:
 
+- **The app's own page, through `apiFetch`** from `use-vibes`. The platform
+  makes the call for the signed-in visitor, so the handler runs as them:
+  `ctx.userInfo` is that visitor, their `ctx.db` writes pass `access.js` as
+  them, and `ctx.connections` spends their connection. A visitor who is not
+  signed in arrives as `ctx.userInfo === null`.
 - **A caller outside the app** — a script, another agent, a server — sends the
   person's vibes.diy token as `Authorization: Bearer <token>`. A missing,
   expired or unrecognised token is not an error: the handler runs with
@@ -686,13 +700,29 @@ Cookies are not read. `ctx.userInfo` is filled in two ways:
 - **The builder's own `call_own_api` check** (see the debugging skill) arrives
   already verified, as the app's owner, with no bearer header.
 
-A plain `fetch("/_api/...")` from `App.jsx` sends neither, so for that call the
-handler sees `ctx.userInfo === null`. That is exactly right for the routes the
-app calls for server work — reading a page, calling a service with a secret —
-which should not depend on who is asking. For anything that depends on the
-signed-in person (their own records, their permissions), build the screen on
-the database hooks, which already know who is signed in; a button that "tests
-the API" from inside the app is testing the anonymous path.
+A plain `fetch("/_api/...")` from `App.jsx` carries no visitor, so the handler
+sees `ctx.userInfo === null`. That suits routes that should not depend on who
+is asking — reading a page, calling a service with a secret. **When a route
+needs to know the visitor — their own records, their connection, their
+permissions — the page calls it with `apiFetch`.** The path is the route under
+`/_api`, and the answer reads like a `Response`:
+
+```jsx file=App.jsx partial
+import { apiFetch } from "use-vibes";
+
+const res = await apiFetch("/my-rsvp", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ going: true }),
+});
+const mine = res.ok ? await res.json() : null;
+```
+
+A route's own error status resolves with `ok: false`; `apiFetch` rejects only
+when the route could not be reached. Bodies are strings, and answers are for
+JSON-sized results rather than exports. Screens that simply list the visitor's
+own records still read best from the database hooks, which already know who is
+signed in.
 
 Writes a handler makes with `ctx.db.put` still pass through `access.js` as the
 caller, so the app's rules hold for API writes too.

package/llms/callai.initial.md

@@ -88,7 +88,7 @@ function TaskCard({ task, database, can, onCorrect, onSaved, disabled }) {
 }
 
 export default function App() {
-  const { database, useLiveQuery } = useFireproof("tasks");
+  const { database, useLiveQuery, writeRejection, clearWriteRejection } = useFireproof("tasks");
   const { me, can, ready } = useVibe("tasks");
   const { docs } = useLiveQuery("type", { key: "task" });
   const [sentence, setSentence] = useState("");
@@ -170,6 +170,7 @@ export default function App() {
     </form>
     <p>{answer}</p>
     <p role="status">{message}</p>
+    {writeRejection && <p role="status">{writeRejection.message} <button type="button" onClick={clearWriteRejection}>Dismiss</button></p>}
     {lastWrite !== undefined && <button type="button" disabled={busy} onClick={undoLast}>Undo</button>}
     {pending !== undefined && !busy && <button type="button" onClick={() => { setPending(undefined); setSentence(""); setCurrent(undefined); }}>Discard unsaved tasks</button>}
     {docs.map((task) => <TaskCard key={task._id} task={task} database={database} can={can} disabled={busy || pending !== undefined} onSaved={(previous) => setLastWrite({ created: [], replaced: previous })} onCorrect={(doc) => { if (busy || pending !== undefined) return; setCurrent(doc); setSentence(""); }} />)}

package/llms/callai.md

@@ -88,7 +88,7 @@ function TaskCard({ task, database, can, onCorrect, onSaved, disabled }) {
 }
 
 export default function App() {
-  const { database, useLiveQuery } = useFireproof("tasks");
+  const { database, useLiveQuery, writeRejection, clearWriteRejection } = useFireproof("tasks");
   const { me, can, ready } = useVibe("tasks");
   const { docs } = useLiveQuery("type", { key: "task" });
   const [sentence, setSentence] = useState("");
@@ -170,6 +170,7 @@ export default function App() {
     </form>
     <p>{answer}</p>
     <p role="status">{message}</p>
+    {writeRejection && <p role="status">{writeRejection.message} <button type="button" onClick={clearWriteRejection}>Dismiss</button></p>}
     {lastWrite !== undefined && <button type="button" disabled={busy} onClick={undoLast}>Undo</button>}
     {pending !== undefined && !busy && <button type="button" onClick={() => { setPending(undefined); setSentence(""); setCurrent(undefined); }}>Discard unsaved tasks</button>}
     {docs.map((task) => <TaskCard key={task._id} task={task} database={database} can={can} disabled={busy || pending !== undefined} onSaved={(previous) => setLastWrite({ created: [], replaced: previous })} onCorrect={(doc) => { if (busy || pending !== undefined) return; setCurrent(doc); setSentence(""); }} />)}

package/llms/connections.md

@@ -27,7 +27,8 @@ a public profile) is an ordinary `ctx.fetch` and needs no connection.
 
 **Declare the provider in `config.connections`, render the Connect button from
 `useConnection`, and read the account through `@vibes.diy/social` or
-`ctx.connections` in `backend.js`.** All three, every time.
+`ctx.connections` in `backend.js`.** All three, every time — and the page
+reaches the third with `apiFetch` (section 4), so it runs as the visitor.
 
 ### 1. Declare it — `backend.js`
 
@@ -172,10 +173,63 @@ with the credential attached by the platform, and
 `await ctx.connections.status(provider)` returns
 `{ state, consented, expiresAt?, accountLabel? }` without spending a call.
 
-**Whose account?** In a `fetch` handler it is the signed-in visitor who called
-the route; in `scheduled` it is the app owner's. A `scheduled` tick can only
-ever read the owner's connection — an app that ranks _each visitor's_ posts
-does that work in `fetch`, when they are there.
+**Whose account?** In a `fetch` handler it is the signed-in visitor the page
+called the route for with `apiFetch` (section 4); in `scheduled` it is the app
+owner's. A `scheduled` tick can only ever read the owner's connection — an app
+that ranks _each visitor's_ posts does that work in `fetch`, when they are there.
+
+### 4. Call it from the page — `apiFetch`
+
+**The page calls its connection-backed routes with `apiFetch` from `use-vibes`, so the
+backend runs as the visitor who connected.** `apiFetch` asks the platform to make
+the call for the signed-in visitor: the handler's `ctx.userInfo` is that
+visitor, and `ctx.connections` and `@vibes.diy/social` spend _their_
+connection. The path is the route under `/_api`, so `apiFetch("/top-posts")`
+reaches the `/top-posts` branch above. Wait for the connection before calling,
+so the first answer is the real one.
+
+```jsx file=App.jsx app=instagram-connection
+import React, { useEffect, useState } from "react";
+import { useConnection, apiFetch } from "use-vibes";
+
+function TopPosts() {
+  const { state, consented } = useConnection("instagram");
+  const connected = consented && (state === "live" || state === "expiring");
+  const [posts, setPosts] = useState([]);
+  const [problem, setProblem] = useState(null);
+  useEffect(() => {
+    if (!connected) return;
+    apiFetch("/top-posts")
+      .then(async (res) => {
+        const data = await res.json();
+        if (res.ok) setPosts(data.posts);
+        else setProblem(`Instagram is ${data.connection ?? "not ready"} — try again in a moment.`);
+      })
+      .catch(() => setProblem("Could not reach the app just now."));
+  }, [connected]);
+  if (!connected) return null;
+  if (problem) return <p>{problem}</p>;
+  return (
+    <ol>
+      {posts.map((p) => (
+        <li key={p.id}>
+          <a href={p.permalink}>{p.caption}</a> — {p.likeCount ?? "hidden"} likes
+        </li>
+      ))}
+    </ol>
+  );
+}
+```
+
+`apiFetch(path, { method, headers, body })` answers like `fetch`: `status`,
+`ok`, `headers`, `text()` and `json()`. The route's own status comes back as
+an answer — a `409` with `{ connection: "needs_consent" }` resolves with
+`ok: false` — and the promise rejects only when the route could not be reached.
+Send JSON as `body: JSON.stringify(data)` with a `content-type:
+application/json` header. A visitor who is not signed in still reaches the
+route, with `ctx.userInfo` set to `null`. The platform keeps the visitor's
+sign-in to itself: `apiFetch` carries who they are, and your code never handles
+a token.
 
 ## Ticks that have nothing to do
 

package/llms/fireproof.initial.md

@@ -21,7 +21,25 @@ Each document has an `_id`, which can be auto-generated or set explicitly. Auto-
 
 Use granular documents, e.g. one document per user action, so saving a form or clicking a button should typically create or update a single document, or just a few documents. Avoid patterns that require a single document to grow without bound.
 
-`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server rejects a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast only when it has one; a reason-less rejection converges silently. So do **not** wrap plain writes in `try/catch` to show denial errors to the user (a save carrying `_files` is the one exception, covered with the image uploader below); keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
+`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server rejects a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast whenever it has one: the app's own `forbidden("…")` text, or the platform's message when a signed-in visitor has no write access to the app (both also reach the app as `writeRejection`, below); a reason-less rejection converges silently. So do **not** wrap plain writes in `try/catch` to show denial errors to the user (a save carrying `_files` is the one exception, covered with the image uploader below); keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
+
+When the server later refuses a write the visitor can act on — a signed-in visitor saving to a private app, say — the platform shows a notice and `useFireproof` hands the app the same reason as `writeRejection` (`{ docId, message }`, or `null` until a save is refused). Render `writeRejection.message` beside the form it came from and call `clearWriteRejection()` when the visitor dismisses it:
+
+```jsx
+function NoteForm({ text }) {
+  const { database, writeRejection, clearWriteRejection } = useFireproof("notes");
+  return (
+    <div>
+      <button onClick={() => database.put({ type: "note", text })}>Save</button>
+      {writeRejection && (
+        <p role="status">
+          {writeRejection.message} <button onClick={clearWriteRejection}>Dismiss</button>
+        </p>
+      )}
+    </div>
+  );
+}
+```
 
 ### Basic Example
 
@@ -97,7 +115,7 @@ function TaskCard({ task, database, can, onCorrect, onSaved, disabled }) {
 }
 
 export default function App() {
-  const { database, useLiveQuery } = useFireproof("tasks");
+  const { database, useLiveQuery, writeRejection, clearWriteRejection } = useFireproof("tasks");
   const { me, can, ready } = useVibe("tasks");
   const { docs } = useLiveQuery("type", { key: "task" });
   const [sentence, setSentence] = useState("");
@@ -179,6 +197,7 @@ export default function App() {
     </form>
     <p>{answer}</p>
     <p role="status">{message}</p>
+    {writeRejection && <p role="status">{writeRejection.message} <button type="button" onClick={clearWriteRejection}>Dismiss</button></p>}
     {lastWrite !== undefined && <button type="button" disabled={busy} onClick={undoLast}>Undo</button>}
     {pending !== undefined && !busy && <button type="button" onClick={() => { setPending(undefined); setSentence(""); setCurrent(undefined); }}>Discard unsaved tasks</button>}
     {docs.map((task) => <TaskCard key={task._id} task={task} database={database} can={can} disabled={busy || pending !== undefined} onSaved={(previous) => setLastWrite({ created: [], replaced: previous })} onCorrect={(doc) => { if (busy || pending !== undefined) return; setCurrent(doc); setSentence(""); }} />)}

package/llms/fireproof.md

@@ -5,7 +5,7 @@ Fireproof is a document database with live sync, designed to make browser apps e
 ## Key Features
 
 - **Apps run anywhere:** Bundle UI, data, and logic together.
-- **Real-Time, local-first:** Writes land in the local replica instantly and sync in the background; the server validates each on ingest and streams the accepted ones live to every viewer. `useLiveQuery` keeps the UI in sync as data arrives, so you render empty states rather than loading spinners — but a synced write can still be rejected on ingest (access denied, conflicts): the local optimistic revision converges **server-wins** — and the platform surfaces the reason **only when the app's access rules provide one**; a reason-less rejection converges silently. Keep the UI reactive to the store rather than depending on a toast; don't assume every write lands, but don't hand-roll denial errors either.
+- **Real-Time, local-first:** Writes land in the local replica instantly and sync in the background; the server validates each on ingest and streams the accepted ones live to every viewer. `useLiveQuery` keeps the UI in sync as data arrives, so you render empty states rather than loading spinners — but a synced write can still be rejected on ingest (access denied, conflicts): the local optimistic revision converges **server-wins** — and the platform surfaces the reason whenever there is one (an access-rule `forbidden("…")`, or no write access for a signed-in visitor); a reason-less rejection converges silently. Keep the UI reactive to the store rather than depending on a toast; don't assume every write lands, but don't hand-roll denial errors either.
 - **Unified API:** TypeScript works with Deno, Bun, Node.js, and the browser.
 - **React Hooks:** Leverage `useLiveQuery` and `useDocument` for live collaboration. Note: these are NOT top-level exports — they are returned by the `useFireproof()` hook. Always destructure from `const { useLiveQuery, useDocument, database } = useFireproof("dbName")`. A child component that was handed `database` may call `useFireproof(database)` instead of repeating the name; it is the same database.
 
@@ -21,7 +21,25 @@ Each document has an `_id`, which can be auto-generated or set explicitly. Auto-
 
 Use granular documents, e.g. one document per user action, so saving a form or clicking a button should typically create or update a single document, or just a few documents. Avoid patterns that require a single document to grow without bound.
 
-`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server's access rules reject a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast **only when the app's access rules provide one** (`forbidden("…")`); a reason-less rejection converges silently. So do **not** wrap plain writes in `try/catch` to show denial errors to the user (a save carrying `_files` is the one exception, covered with the image uploader below); keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
+`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server's access rules reject a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast whenever there is one: the app's own `forbidden("…")` text, or the platform's message when a signed-in visitor has no write access to the app (both also reach the app as `writeRejection`, below); a reason-less rejection converges silently. So do **not** wrap plain writes in `try/catch` to show denial errors to the user (a save carrying `_files` is the one exception, covered with the image uploader below); keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
+
+When the server later refuses a write the visitor can act on — a signed-in visitor saving to a private app, say — the platform shows a notice and `useFireproof` hands the app the same reason as `writeRejection` (`{ docId, message }`, or `null` until a save is refused). Render `writeRejection.message` beside the form it came from and call `clearWriteRejection()` when the visitor dismisses it:
+
+```jsx
+function NoteForm({ text }) {
+  const { database, writeRejection, clearWriteRejection } = useFireproof("notes");
+  return (
+    <div>
+      <button onClick={() => database.put({ type: "note", text })}>Save</button>
+      {writeRejection && (
+        <p role="status">
+          {writeRejection.message} <button onClick={clearWriteRejection}>Dismiss</button>
+        </p>
+      )}
+    </div>
+  );
+}
+```
 
 ### Basic Example
 
@@ -97,7 +115,7 @@ function TaskCard({ task, database, can, onCorrect, onSaved, disabled }) {
 }
 
 export default function App() {
-  const { database, useLiveQuery } = useFireproof("tasks");
+  const { database, useLiveQuery, writeRejection, clearWriteRejection } = useFireproof("tasks");
   const { me, can, ready } = useVibe("tasks");
   const { docs } = useLiveQuery("type", { key: "task" });
   const [sentence, setSentence] = useState("");
@@ -179,6 +197,7 @@ export default function App() {
     </form>
     <p>{answer}</p>
     <p role="status">{message}</p>
+    {writeRejection && <p role="status">{writeRejection.message} <button type="button" onClick={clearWriteRejection}>Dismiss</button></p>}
     {lastWrite !== undefined && <button type="button" disabled={busy} onClick={undoLast}>Undo</button>}
     {pending !== undefined && !busy && <button type="button" onClick={() => { setPending(undefined); setSentence(""); setCurrent(undefined); }}>Discard unsaved tasks</button>}
     {docs.map((task) => <TaskCard key={task._id} task={task} database={database} can={can} disabled={busy || pending !== undefined} onSaved={(previous) => setLastWrite({ created: [], replaced: previous })} onCorrect={(doc) => { if (busy || pending !== undefined) return; setCurrent(doc); setSentence(""); }} />)}
@@ -506,7 +525,7 @@ App.jsx
 
 ## Offline writes are on by default (`offlineQueue`)
 
-For signed-in users, writes are **local-first by default**: a `put`/`del` that fails on the network is durably queued on the device (it resolves, stays visible, and syncs to the cloud when you're back online) instead of rolling back. You don't opt in — every signed-in vibe gets this. An access-denied/validation rejection is **not** queued: it converges **server-wins** (the local optimistic revision is overwritten by the server's version); the platform surfaces the reason only when the app's access rules provide one, and a reason-less rejection converges silently — so keep the UI reactive to the store rather than depending on a toast. Only transport failures queue and retry.
+For signed-in users, writes are **local-first by default**: a `put`/`del` that fails on the network is durably queued on the device (it resolves, stays visible, and syncs to the cloud when you're back online) instead of rolling back. You don't opt in — every signed-in vibe gets this. An access-denied/validation rejection is **not** queued: it converges **server-wins** (the local optimistic revision is overwritten by the server's version); the platform surfaces the reason whenever there is one, and a reason-less rejection converges silently — so keep the UI reactive to the store rather than depending on a toast. Only transport failures queue and retry.
 
 Pass `{ offlineQueue: false }` for **server-first, fail-fast** writes: a `put` resolves only when the server accepts it, and a network failure rejects immediately with nothing queued. Choose this for **collaborative multi-writer apps** where two people may edit the same doc — sync is blind last-arrival-wins (Firefly has no `_rev`), so a stale write replayed on reconnect can silently overwrite a newer one. When a lost write is safer than a surprise overwrite, opt out.
 
@@ -532,7 +551,7 @@ The old `{ anonymousLocal: true }` option (and its `migrate` hook) is **deprecat
 
 ## Architecture: Where's My Data?
 
-Data lives in a local replica (IndexedDB) that the app reads and writes instantly; that replica syncs to the Firefly server in the background. The server is the authority on acceptance — each synced write is validated by the app's access rules on ingest, persisted, and then synced to all users who have read access. A write that fails validation or hits a conflict is rejected on ingest: the local optimistic revision converges **server-wins**, and the platform surfaces the reason **only when the app's access rules provide one** — a reason-less rejection converges silently, so keep the UI reactive to the store rather than depending on a toast. Don't assume the write always lands, but don't hand-roll your own denial error UI — let it converge.
+Data lives in a local replica (IndexedDB) that the app reads and writes instantly; that replica syncs to the Firefly server in the background. The server is the authority on acceptance — each synced write is validated by the app's access rules on ingest, persisted, and then synced to all users who have read access. A write that fails validation or hits a conflict is rejected on ingest: the local optimistic revision converges **server-wins**, and the platform surfaces the reason whenever there is one — a reason-less rejection converges silently, so keep the UI reactive to the store rather than depending on a toast. Don't assume the write always lands, but don't hand-roll your own denial error UI — let it converge.
 
 ## Using Fireproof in JavaScript
 

package/package.json

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