@vibes.diy/prompts 2.5.0 → 2.5.1

package/llms/fireproof.md

@@ -59,14 +59,16 @@ export default function App() {
 }
 ```
 
-The access function lives in a separate file. Even simple apps include one — it's the server-side authority for who can write:
+The access function lives in a separate file. Even simple apps include one — it's the server-side authority for who can write, and it routes each document to a channel so the author can read it back:
 
 access.js
 
 ```js
 export default function (doc, oldDoc, user) {
   if (!user) throw { forbidden: "sign in to save" };
-  return {};
+  // Private to the author: one channel per user holds all of their documents.
+  const mine = `user:${user.userHandle}`;
+  return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };
 }
 ```
 
@@ -376,7 +378,7 @@ export function announcements(doc, oldDoc, user, ctx) {
     return { channels: [doc.channel] };
   }
 
-  return {};
+  throw { forbidden: "unknown document type" };
 }
 ```
 
@@ -474,7 +476,7 @@ export function chat(doc, oldDoc, user, ctx) {
     return { channels: [doc.channel] };
   }
 
-  return {};
+  throw { forbidden: "unknown document type" };
 }
 ```
 
@@ -523,7 +525,7 @@ Access functions live in `/access.js`, a separate file in the vibe's filesystem
 
 ### AccessDescriptor return type
 
-All fields are optional. `{}` is a valid return. `throw { forbidden: "reason" }` rejects the write.
+All fields are optional, but a stored document must be routed to at least one channel (`channels`) to be readable — a result with no channels is refused at write time. To reject a write outright, `throw { forbidden: "reason" }`.
 
 ```ts
 type AccessDescriptor = {
@@ -553,6 +555,15 @@ type AccessDescriptor = {
 
 **Access functions are server-enforced policy code.** Checks should be deterministic over `(doc, oldDoc, user, ctx)` and deny with `throw { forbidden: "reason" }` when violated.
 
+### Choosing channels — keep the count low
+
+A channel is a _reusable_ unit of read access: grant a user into a channel once and they can read every document routed there. Reach for the smallest number of channels the sharing actually requires.
+
+- **A reusable group reads many docs** (a team, a board, a project): route to one channel the _collaboration_ owns — `return { channels: [doc.channelId] }` — and grant membership once via a meta or invite doc. Many documents share the one channel.
+- **Only the author reads it** (private notes, a user's own uploads): route to one channel the _user_ owns. `const mine = \`user:${user.userHandle}\`; return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };` — all of that user's private documents live in this single channel.
+- **A document goes to a one-off set with no reusable group:** route to several channels at once — `return { channels: [\`user:${aHandle}\`, \`user:${bHandle}\`] }`. Mint a per-document channel (`channels: [doc._id]`) only when each document genuinely has its own disjoint audience.
+- **Refusing a write:** `throw { forbidden: "reason" }`. Every document you store is routed to at least one channel so it can be read back.
+
 ### Example: Workspace chat with channels
 
 access.js
@@ -587,7 +598,7 @@ export function chat(doc, oldDoc, user, ctx) {
     };
   }
 
-  return {};
+  throw { forbidden: "unknown document type" };
 }
 ```
 
@@ -620,8 +631,7 @@ export function survey(doc, oldDoc, user, ctx) {
     return { channels: [doc._id], grant: { public: [doc._id] } };
   }
 
-  if (!user) throw { forbidden: "authentication required" };
-  return {};
+  throw { forbidden: "unknown document type" };
 }
 ```
 
@@ -642,7 +652,9 @@ export function chat(doc, oldDoc, user, ctx) {
 
 export function notes(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "authentication required" };
-  return {};
+  // Private to the author — one channel per user.
+  const mine = `user:${user.userHandle}`;
+  return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };
 }
 ```
 
@@ -674,10 +686,11 @@ export function chat(doc, oldDoc, user, ctx) {
   return { channels: [doc.channelId] };
 }
 
-// Everything else: require authentication, no channel routing
+// Everything else: authenticated users get a private per-user channel
 export default function (doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "authentication required" };
-  return {};
+  const mine = `user:${user.userHandle}`;
+  return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };
 }
 ```
 
@@ -908,7 +921,9 @@ access.js
 ```js
 export function imageUploads(doc, oldDoc, user) {
   if (!user) throw { forbidden: "sign in to upload" };
-  return {};
+  // Each uploader reads their own images — one private channel per user.
+  const mine = `user:${user.userHandle}`;
+  return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };
 }
 ```
 
@@ -1044,6 +1059,8 @@ export function todoList(doc, oldDoc, user) {
   if (doc.type === "todo" && doc.createdBy !== user.userHandle) {
     throw { forbidden: "only the author can edit" };
   }
-  return {};
+  // Private to the author — one channel per user.
+  const mine = `user:${user.userHandle}`;
+  return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };
 }
 ```

package/llms/use-viewer.md

@@ -34,7 +34,7 @@ export default function App() {
 
 ## What you get
 
-- `viewer` — `{ userHandle, displayName?, avatarUrl }` or `null` for anonymous visitors. `avatarUrl` is a stable opaque URL — just use it in `<img src>`, don't construct it yourself.
+- `viewer` — `{ userHandle, displayName? }` or `null` for anonymous visitors. Avatars are not on the payload — render them with `<ViewerTag userHandle={...} />`, which resolves the avatar from the handle. Don't build avatar URLs yourself.
 - `isViewerPending` — `true` while the platform is still resolving the viewer identity (e.g. on first render before the parent shell has pushed the identity update). **Gate any auth-dependent UI on `!isViewerPending`** to avoid flashing the wrong state. Once it becomes `false`, `viewer` is either populated or definitively `null`.
 - `isOwner` — `true` when the viewer owns this vibe. Use it for management UI (settings, role grants, moderation).
 - `can(action, dbName?)` — `true`/`false` for `"read"`, `"write"`, `"delete"`. Checks app-level ACLs. In most apps `viewer` and `access.hasRole()`/`access.hasChannel()` are the right gates instead.
@@ -147,7 +147,7 @@ export default function App() {
 Key points:
 
 - **Stamp `authorHandle` at write time** — persist the author's handle on the doc. Render with `<ViewerTag userHandle={authorHandle} />` which resolves display name and avatar automatically.
-- **`avatarUrl` is stable** — if the author changes their avatar, the URL stays the same and the bytes update. ViewerTag handles this for you.
+- **Avatars are stable** — ViewerTag resolves the avatar from the handle; if the author changes their avatar, the URL stays the same and the bytes update. ViewerTag handles this for you.
 - **One source of identity** — persist `authorHandle` on the doc. ViewerTag does the rest.
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -30,8 +30,8 @@
     "@fireproof/core-types-base": "~0.24.19",
     "@fireproof/core-types-protocols-cloud": "~0.24.19",
     "@fireproof/use-fireproof": "~0.24.19",
-    "@vibes.diy/call-ai-v2": "^2.5.0",
-    "@vibes.diy/use-vibes-types": "^2.5.0",
+    "@vibes.diy/call-ai-v2": "^2.5.1",
+    "@vibes.diy/use-vibes-types": "^2.5.1",
     "arktype": "~2.2.0",
     "json-schema-faker": "~0.6.1"
   },

package/system-prompt-initial.md

@@ -14,7 +14,7 @@ You are an AI assistant tasked with creating React components. You should create
 - Use `callAI` to fetch AI, use schema like this: `JSON.parse(await callAI(prompt, { schema: { properties: { todos: { type: 'array', items: { type: 'string' } } } } }))` and save final responses as individual Fireproof documents.
 - Always show loading states during any async operation (callAI, fetch, database queries): use a useState boolean (e.g. `isLoading`), set it true before the call and false in .finally(). While loading: (1) disable the trigger button with `disabled={isLoading}`, (2) replace the button text with a spinning SVG icon using CSS animation `animate-spin` (a simple circle with a gap), (3) optionally show a short status text like 'Loading...' near the button. Never leave the user clicking a button with no visual feedback. Pattern: `setIsLoading(true); try { await callAI(...); } finally { setIsLoading(false); }`
 - For file uploads use drag and drop and store using the `doc._files` API; for AI image generation use `<ImgGen prompt="..." />`
-- Access control is decided by the runtime, not by your code. `useViewer()` from `"use-vibes"` gives you `const { viewer, isOwner, isViewerPending, ViewerTag } = useViewer();`. `viewer` is `{ userHandle, displayName?, avatarUrl } | null` (null for anonymous). **Gate write surfaces on `viewer`** — show forms only when signed in, render a read-only fallback otherwise. For apps with an access function (`access.js`), gate further with `access.hasRole()` or `access.hasChannel()` from `useFireproof()` — never re-derive permissions from document fields client-side. Use `isOwner` for management UI (settings, moderation). Render avatars with `<ViewerTag userHandle={authorHandle} />`. This applies to every app — never skip useViewer because the app "sounds single-user"; the runtime decides sharing, not the prompt. See use-viewer docs.
+- Access control is decided by the runtime, not by your code. `useViewer()` from `"use-vibes"` gives you `const { viewer, isOwner, isViewerPending, ViewerTag } = useViewer();`. `viewer` is `{ userHandle, displayName? } | null` (null for anonymous). **Gate write surfaces on `viewer`** — show forms only when signed in, render a read-only fallback otherwise. For apps with an access function (`access.js`), gate further with `access.hasRole()` or `access.hasChannel()` from `useFireproof()` — never re-derive permissions from document fields client-side. Use `isOwner` for management UI (settings, moderation). Render avatars with `<ViewerTag userHandle={authorHandle} />`. This applies to every app — never skip useViewer because the app "sounds single-user"; the runtime decides sharing, not the prompt. See use-viewer docs.
 - Don't try to generate png or base64 data, use placeholder image APIs instead, like https://picsum.photos/400 where 400 is the square size
 - Never use emojis in the UI. Use inline SVG icons instead — simple, single-color, stroke-based SVGs (24x24 viewBox, strokeWidth 2, strokeLinecap round, strokeLinejoin round). Build icons directly in JSX, do not import icon libraries.
 - List data items on the main page of your app so users don't have to hunt for them
@@ -66,7 +66,7 @@ Target ~40–60 lines. The shell should look like a real app with empty sections
 >     ctx.requireAccess(doc.channelId)
 >     return { channels: [doc.channelId] }
 >   }
->   return {}
+>   throw { forbidden: "unknown document type" }
 > }
 > ```
 

package/system-prompt.md

@@ -14,7 +14,7 @@ You are an AI assistant tasked with creating React components. You should create
 - Use `callAI` to fetch AI, use schema like this: `JSON.parse(await callAI(prompt, { schema: { properties: { todos: { type: 'array', items: { type: 'string' } } } } }))` and save final responses as individual Fireproof documents.
 - Always show loading states during any async operation (callAI, fetch, database queries): use a useState boolean (e.g. `isLoading`), set it true before the call and false in .finally(). While loading: (1) disable the trigger button with `disabled={isLoading}`, (2) replace the button text with a spinning SVG icon using CSS animation `animate-spin` (a simple circle with a gap), (3) optionally show a short status text like 'Loading...' near the button. Never leave the user clicking a button with no visual feedback. Pattern: `setIsLoading(true); try { await callAI(...); } finally { setIsLoading(false); }`
 - For file uploads use drag and drop and store using the `doc._files` API; for AI image generation use `<ImgGen prompt="..." />`
-- Access control is decided by the runtime, not by your code. `useViewer()` from `"use-vibes"` gives you `const { viewer, isOwner, isViewerPending, ViewerTag } = useViewer();`. `viewer` is `{ userHandle, displayName?, avatarUrl } | null` (null for anonymous). **Gate write surfaces on `viewer`** — show forms only when signed in, render a read-only fallback otherwise. For apps with an access function (`access.js`), gate further with `access.hasRole()` or `access.hasChannel()` from `useFireproof()` — never re-derive permissions from document fields client-side. Use `isOwner` for management UI (settings, moderation). Render avatars with `<ViewerTag userHandle={authorHandle} />`. This applies to every app — never skip useViewer because the app "sounds single-user"; the runtime decides sharing, not the prompt. See use-viewer docs.
+- Access control is decided by the runtime, not by your code. `useViewer()` from `"use-vibes"` gives you `const { viewer, isOwner, isViewerPending, ViewerTag } = useViewer();`. `viewer` is `{ userHandle, displayName? } | null` (null for anonymous). **Gate write surfaces on `viewer`** — show forms only when signed in, render a read-only fallback otherwise. For apps with an access function (`access.js`), gate further with `access.hasRole()` or `access.hasChannel()` from `useFireproof()` — never re-derive permissions from document fields client-side. Use `isOwner` for management UI (settings, moderation). Render avatars with `<ViewerTag userHandle={authorHandle} />`. This applies to every app — never skip useViewer because the app "sounds single-user"; the runtime decides sharing, not the prompt. See use-viewer docs.
 - Don't try to generate png or base64 data, use placeholder image APIs instead, like https://picsum.photos/400 where 400 is the square size
 - Never use emojis in the UI. Use inline SVG icons instead — simple, single-color, stroke-based SVGs (24x24 viewBox, strokeWidth 2, strokeLinecap round, strokeLinejoin round). Build icons directly in JSX, do not import icon libraries.
 - Consider and potentially reuse/extend code from previous responses if relevant
@@ -274,7 +274,7 @@ When the app uses channel-based read isolation or per-document write validation,
 >     ctx.requireAccess(doc.channelId);
 >     return { channels: [doc.channelId] };
 >   }
->   return {};
+>   throw { forbidden: "unknown document type" };
 > }
 > ```