@vibes.diy/prompts 14.3.79 → 14.3.81

package/llms/fireproof.md

@@ -29,14 +29,17 @@ When the server later refuses a write the visitor can act on — a signed-in vis
 function NoteForm({ text }) {
   const { database, writeRejection, clearWriteRejection } = useFireproof("notes");
   return (
-    <div>
-      <button onClick={() => database.put({ type: "note", text })}>Save</button>
+    <Stack gap={2}>
+      <Row>
+        <Button type="button" onClick={() => database.put({ type: "note", text })}>Save</Button>
+      </Row>
       {writeRejection && (
-        <p role="status">
-          {writeRejection.message} <button onClick={clearWriteRejection}>Dismiss</button>
-        </p>
+        <Row gap={2} align="center" wrap>
+          <p role="status">{writeRejection.message}</p>
+          <Button type="button" size="sm" variant="quiet" onClick={clearWriteRejection}>Dismiss</Button>
+        </Row>
       )}
-    </div>
+    </Stack>
   );
 }
 ```
@@ -53,6 +56,7 @@ import React, { useState } from "react";
 import { callAI } from "call-ai";
 import { useFireproof } from "use-fireproof";
 import { useVibe } from "use-vibes";
+import { Button, Field, Heading, Input, Row, RowCard, Stack, Text, Textarea } from "@vibes.diy/pouf";
 
 const taskSchema = {
   type: "object",
@@ -100,19 +104,23 @@ function TaskCard({ task, database, can, onCorrect, onSaved, disabled }) {
   const { useDocument } = useFireproof(database);
   const { doc, merge, save } = useDocument(task);
   const [editing, setEditing] = useState(false);
-  return <article>
-    <h2>{task.title}</h2><p>{task.details}</p><p>{task.dueDate}</p>
+  return <RowCard><Stack gap={2}>
+    <Text>{task.title}</Text><Text muted>{task.details}</Text><Text muted>{task.dueDate}</Text>
     {can.edit(task).ok && <>
-      <button type="button" disabled={disabled} onClick={() => onCorrect(task)}>Change by sentence</button>
-      <button type="button" disabled={disabled} onClick={() => setEditing(true)}>Edit details</button>
+      <Row gap={2} wrap>
+        <Button type="button" size="sm" variant="quiet" disabled={disabled} onClick={() => onCorrect(task)}>Change by sentence</Button>
+        <Button type="button" size="sm" variant="quiet" disabled={disabled} onClick={() => setEditing(true)}>Edit details</Button>
+      </Row>
       {editing && <form onSubmit={async (event) => { event.preventDefault(); if (disabled) return; await save(); onSaved(task); setEditing(false); }}>
-        <input disabled={disabled} aria-label="Task" value={doc.title} onChange={(event) => merge({ title: event.target.value })} />
-        <textarea disabled={disabled} aria-label="Details" value={doc.details} onChange={(event) => merge({ details: event.target.value })} />
-        <input disabled={disabled} aria-label="Due date" type="date" value={doc.dueDate} onChange={(event) => merge({ dueDate: event.target.value })} />
-        <button type="submit" disabled={disabled}>Save details</button>
+        <Stack gap={3}>
+          <Field label="Task">{(id, describedBy) => <Input id={id} describedBy={describedBy} disabled={disabled} value={doc.title} onChange={(title) => merge({ title })} />}</Field>
+          <Field label="Details">{(id, describedBy) => <Textarea id={id} describedBy={describedBy} disabled={disabled} value={doc.details} onChange={(details) => merge({ details })} />}</Field>
+          <Field label="Due date">{(id, describedBy) => <Input id={id} describedBy={describedBy} disabled={disabled} type="date" value={doc.dueDate} onChange={(dueDate) => merge({ dueDate })} />}</Field>
+          <Row><Button type="submit" size="sm" variant="quiet" disabled={disabled}>Save details</Button></Row>
+        </Stack>
       </form>}
     </>}
-  </article>;
+  </Stack></RowCard>;
 }
 
 export default function App() {
@@ -188,21 +196,27 @@ export default function App() {
       setMessage(error.message);
     } finally { setBusy(false); }
   }
-  return <main>
-    <h1>Tasks in your own words</h1>
+  return <main className="min-h-screen bg-background text-foreground font-sans p-6"><Stack gap={5}>
+    <Heading level={1}>Tasks in your own words</Heading>
     <form onSubmit={submitSentence}>
-      <textarea aria-label="Describe tasks, a correction, or ask a question" value={sentence} disabled={busy || pending !== undefined} onChange={(event) => setSentence(event.target.value)} />
-      {current !== undefined && <p>Changing: {current.title} <button type="button" disabled={busy || pending !== undefined} onClick={() => { setCurrent(undefined); setSentence(""); }}>Add a new task</button></p>}
-      <button type="submit" disabled={!ready || busy || sentence.trim().length === 0}>{busy ? "Adding your changes…" : pending !== undefined ? "Retry remaining tasks" : current === undefined ? "Add tasks" : "Apply correction"}</button>
-      <button type="button" disabled={!ready || busy || pending !== undefined || sentence.trim().length === 0} onClick={askRecords}>Ask about tasks</button>
+      <Stack gap={3}>
+        <Field label="Describe tasks, a correction, or ask a question">{(id, describedBy) => <Textarea id={id} describedBy={describedBy} value={sentence} disabled={busy || pending !== undefined} onChange={setSentence} />}</Field>
+        {current !== undefined && <Row gap={2} align="center" wrap><Text muted>Changing: {current.title}</Text><Button type="button" size="sm" variant="quiet" disabled={busy || pending !== undefined} onClick={() => { setCurrent(undefined); setSentence(""); }}>Add a new task</Button></Row>}
+        <Row gap={2} wrap>
+          <Button type="submit" disabled={!ready || busy || sentence.trim().length === 0}>{busy ? "Adding your changes…" : pending !== undefined ? "Retry remaining tasks" : current === undefined ? "Add tasks" : "Apply correction"}</Button>
+          <Button type="button" variant="quiet" disabled={!ready || busy || pending !== undefined || sentence.trim().length === 0} onClick={askRecords}>Ask about tasks</Button>
+        </Row>
+      </Stack>
     </form>
-    <p>{answer}</p>
+    <Text>{answer}</Text>
     <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>}
+    {writeRejection && <Row gap={2} align="center" wrap><p role="status">{writeRejection.message}</p><Button type="button" size="sm" variant="quiet" onClick={clearWriteRejection}>Dismiss</Button></Row>}
+    <Row gap={2} wrap>
+      {lastWrite !== undefined && <Button type="button" size="sm" variant="quiet" disabled={busy} onClick={undoLast}>Undo</Button>}
+      {pending !== undefined && !busy && <Button type="button" size="sm" variant="quiet" tone="down" onClick={() => { setPending(undefined); setSentence(""); setCurrent(undefined); }}>Discard unsaved tasks</Button>}
+    </Row>
     {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(""); }} />)}
-  </main>;
+  </Stack></main>;
 }
 ```
 
@@ -337,9 +351,15 @@ To update an existing document from a click handler or callback, use `database.p
 =======
           <li key={doc._id}>
             {doc.text}
-            <button onClick={() => database.put({ ...doc, favorite: !doc.favorite })}>
-              {doc.favorite ? "★" : "☆"}
-            </button>
+            <IconButton
+              size="sm"
+              variant={doc.favorite ? "solid" : "quiet"}
+              tone="warn"
+              aria-pressed={Boolean(doc.favorite)}
+              label={doc.favorite ? "Unfavorite" : "Favorite"}
+              icon={<Icon name="star" size="sm" />}
+              onClick={() => database.put({ ...doc, favorite: !doc.favorite })}
+            />
           </li>
 >>>>>>> REPLACE
 ```
@@ -348,7 +368,17 @@ Never call hooks inside handlers — `const { doc, save } = useDocument({ _id: i
 
 ### Continuous Controls — `merge()` on every event, `save()` once on commit
 
-A continuous control (slider, drag, color picker, live-typed text bound to one doc) fires many events in quick succession. **Never call `database.put()` or `save()` on every `onChange`** — that floods the server with rapid concurrent writes to the same `_id`, which collide on the per-document sequence and get rejected (`Failed to put document …`). Instead, `merge()` locally on each event to keep the UI live, and `save()` once when the interaction commits (`onPointerUp`, `onBlur`, `onChange` for a range input's final value, or a debounced trailing call). Editing a single doc with a slider:
+A continuous control (slider, drag, color picker, live-typed text bound to one doc) fires many events in quick succession. **Never call `database.put()` or `save()` on every `onChange`** — that floods the server with rapid concurrent writes to the same `_id`, which collide on the per-document sequence and get rejected (`Failed to put document …`). Instead, `merge()` on each event to keep the UI live (it updates the local draft and, when the doc has an `_id`, broadcasts the merged snapshot to connected peers, but persists nothing), and `save()` once when the interaction commits (`onPointerUp`, `onBlur`, or a debounced trailing call; a `Slider`'s `onChange` fires on every step, so it is not a commit, and the wrapper around it hears the release). Editing a single doc with a slider:
+
+### `App.jsx`
+```jsx
+<<<<<<< SEARCH
+import { useFireproof } from "use-fireproof";
+=======
+import { useFireproof } from "use-fireproof";
+import { Slider } from "@vibes.diy/pouf/interactive";
+>>>>>>> REPLACE
+```
 
 ### `App.jsx`
 ```jsx
@@ -359,6 +389,7 @@ A continuous control (slider, drag, color picker, live-typed text bound to one d
 
   // One shared mix doc; slider updates the UI on every event, persists on commit
   const { doc: mix, merge: mergeMix, save: saveMix } = useDocument({ _id: "mix:current", level: 50 });
+  const SLIDER_KEYS = new Set(["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End", "PageUp", "PageDown"]);
 >>>>>>> REPLACE
 ```
 
@@ -367,14 +398,16 @@ A continuous control (slider, drag, color picker, live-typed text bound to one d
 <<<<<<< SEARCH
       <h3>Recent Documents</h3>
 =======
-      <input
-        type="range"
-        min="0"
-        max="100"
-        value={mix.level}
-        onChange={(e) => mergeMix({ level: Number(e.target.value) })} // live, no write
+      <div
         onPointerUp={() => saveMix().catch((err) => console.error("save failed", err))} // one write on commit
-      />
+        onKeyUp={(e) => {
+          // only the keys that move the slider commit; Tab or focusing it writes nothing
+          if (SLIDER_KEYS.has(e.key)) saveMix().catch((err) => console.error("save failed", err));
+        }}
+      >
+        {/* live, no write */}
+        <Slider label="Level" min={0} max={100} value={[mix.level]} onChange={([level]) => mergeMix({ level })} />
+      </div>
 
       <h3>Recent Documents</h3>
 >>>>>>> REPLACE
@@ -382,6 +415,127 @@ A continuous control (slider, drag, color picker, live-typed text bound to one d
 
 If you genuinely need to persist mid-drag, debounce the `save()` so at most one write is in flight, and still `.catch()` the rejection. Better yet, prefer one document per event (see the Counter Pattern) over hammering a single hot document.
 
+### Strokes — `merge()` the gesture live, save its cells once on pointer-up
+
+A drag that touches many documents (painting pixels, drawing on a shared board) splits the same way: **the stroke is live, the cells are durable.** Keep the in-progress stroke in a per-person draft (`_id: "stroke:" + handle`) and `merge()` each new cell into it on `onPointerMove`; peers see it as it is drawn, because `merge()` broadcasts the draft and their `useLiveQuery` returns it as a row. On `onPointerUp`, `put()` one document per touched cell, then `merge()` the stroke back to empty. Never `put()` from `onPointerMove`: one quick drag becomes dozens of writes in flight.
+
+Keep each cell its own document with a deterministic `_id` (`pixel-<x>-<y>`). Never fold the canvas into one document every visitor saves: the server keeps whichever save arrives last, so one visitor's save erases everyone else's strokes. An unsaved draft drops out for peers about 12 seconds after it stops updating.
+
+A draft reaches only the peers already subscribed to its channel, and a channel's grant comes from a saved document. Create a fixed-id room record on that channel (see Required starting records) so even the first stroke on an empty canvas is seen live.
+
+### `App.jsx`
+```jsx
+import React, { useEffect, useRef } from "react";
+import { useFireproof } from "use-fireproof";
+import { useViewer, useVibe } from "use-vibes";
+import { Button } from "@vibes.diy/pouf";
+
+const SIZE = 32;
+const CELL = 16;
+const COLOR = "#3a86ff";
+
+export default function App() {
+  const { viewer, isViewerPending, requestLogin } = useViewer();
+  if (isViewerPending) return null;
+  if (!viewer) return <Button type="button" onClick={requestLogin}>Sign in to paint</Button>;
+  return <Canvas key={viewer.userHandle} me={viewer.userHandle} />; // fixed draft _id per painter
+}
+
+function Canvas({ me }) {
+  // Many people write the same pixel docs: fail fast rather than replay a stale queued write.
+  const { database, useLiveQuery, useDocument, writeRejection } = useFireproof("pixels", { offlineQueue: false });
+  const { ready, can } = useVibe("pixels");
+  const canPaint = ready && can.create({ _id: "pixel-0-0", type: "pixel", x: 0, y: 0, color: COLOR, paintedBy: me }).ok;
+  const { docs: pixels } = useLiveQuery("type", { key: "pixel" });
+  const { docs: strokes } = useLiveQuery("type", { key: "stroke" });
+  const { doc: stroke, merge: mergeStroke } = useDocument({ _id: "stroke:" + me, type: "stroke", userHandle: me, color: COLOR, cells: [] });
+  const cellsRef = useRef([]);
+  const canvasRef = useRef(null);
+
+  useEffect(() => {
+    // The room record grants the channel, so peers subscribe before the first stroke.
+    const room = { _id: "canvas:main", type: "canvas" };
+    if (ready && can.create(room).ok) database.put(room);
+  }, [ready, can, database]);
+
+  useEffect(() => {
+    const ctx = canvasRef.current.getContext("2d");
+    ctx.fillStyle = "#ffffff";
+    ctx.fillRect(0, 0, SIZE * CELL, SIZE * CELL);
+    const fill = (x, y, color) => {
+      ctx.fillStyle = color;
+      ctx.fillRect(x * CELL, y * CELL, CELL, CELL);
+    };
+    for (const p of pixels) fill(p.x, p.y, p.color);
+    for (const s of strokes) if (s.userHandle !== me) for (const [x, y] of s.cells ?? []) fill(x, y, s.color);
+    for (const [x, y] of stroke.cells) fill(x, y, stroke.color);
+  }, [pixels, strokes, stroke, me]);
+
+  function extendStroke(e) {
+    if (!canPaint) return;
+    const r = canvasRef.current.getBoundingClientRect();
+    const x = Math.floor(((e.clientX - r.left) / r.width) * SIZE);
+    const y = Math.floor(((e.clientY - r.top) / r.height) * SIZE);
+    if (x < 0 || y < 0 || x >= SIZE || y >= SIZE) return;
+    if (cellsRef.current.some((c) => c[0] === x && c[1] === y)) return;
+    cellsRef.current = [...cellsRef.current, [x, y]];
+    mergeStroke({ cells: cellsRef.current }); // live for everyone, no write
+  }
+  async function endStroke() {
+    const cells = cellsRef.current;
+    cellsRef.current = [];
+    const writes = [];
+    for (const [x, y] of cells) writes.push(database.put({ _id: `pixel-${x}-${y}`, type: "pixel", x, y, color: COLOR, paintedBy: me }));
+    await Promise.all(writes); // the durable commit: one write per touched cell
+    if (cellsRef.current.length === 0) mergeStroke({ cells: [] }); // unless a newer stroke began
+  }
+
+  return (
+    <div>
+      {writeRejection && <p role="status">{writeRejection.message}</p>}
+      <canvas
+        ref={canvasRef}
+        width={SIZE * CELL}
+        height={SIZE * CELL}
+        className="w-full max-w-lg aspect-square touch-none"
+        onPointerDown={(e) => {
+          e.currentTarget.setPointerCapture(e.pointerId);
+          extendStroke(e);
+        }}
+        onPointerMove={(e) => e.buttons && extendStroke(e)}
+        onPointerUp={endStroke}
+        onPointerCancel={endStroke}
+      />
+    </div>
+  );
+}
+```
+
+The access rules see the broadcast draft too, so `stroke` needs its own branch that binds the `_id` to the sender:
+
+### `access.js`
+```js
+export default function (doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in to paint" };
+  const inGrid = (n) => Number.isInteger(n) && n >= 0 && n < 32;
+  if (doc.type === "canvas") {
+    if (doc._id !== "canvas:main") throw { forbidden: "one canvas" };
+    return { channels: ["canvas"], grant: { public: ["canvas"] } };
+  }
+  if (doc.type === "stroke") {
+    if (doc._id !== "stroke:" + user.userHandle || doc.userHandle !== user.userHandle) throw { forbidden: "not your stroke" };
+    if (!Array.isArray(doc.cells) || doc.cells.length > 1024 || !doc.cells.every((c) => Array.isArray(c) && c.length === 2 && inGrid(c[0]) && inGrid(c[1]))) throw { forbidden: "bad stroke" };
+    return { channels: ["canvas"], grant: { public: ["canvas"] } };
+  }
+  if (doc.type === "pixel") {
+    if (!inGrid(doc.x) || !inGrid(doc.y) || doc._id !== `pixel-${doc.x}-${doc.y}`) throw { forbidden: "pixel out of bounds" };
+    if (doc.paintedBy !== user.userHandle) throw { forbidden: "not your paint" };
+    return { channels: ["canvas"], grant: { public: ["canvas"] } };
+  }
+  throw { forbidden: "unknown document type" };
+}
+```
+
 ### Query Data
 
 Data is queried by sorted indexes defined by the application. Sort by strings, numbers, or booleans, as well as arrays for grouping. Use numbers when possible for sorting continuous data. You can use the `_id` field for temporal sorting so you don't have to write code to get simple recent document lists, as in the basic example above.
@@ -620,7 +774,7 @@ Building an image uploader with `_files`:
 ```jsx
 import React from "react";
 import { useFireproof } from "use-fireproof";
-import { Button, Card, CardContent, Input, Label } from "@vibes.diy/look";
+import { Button, Card, ErrorNote, Field, Figure, Grid, Heading, Input, Stack, Text } from "@vibes.diy/pouf";
 
 export default function App() {
   const { useDocument, useLiveQuery } = useFireproof("imageUploads");
@@ -654,46 +808,45 @@ export default function App() {
   };
 
   const c = {
-    page: "bg-background text-foreground font-sans",
-    meta: "text-muted-foreground",
+    page: "min-h-screen p-6 max-w-lg mx-auto bg-background text-foreground font-sans",
   };
 
   return (
-    <div className={`min-h-screen p-6 max-w-lg mx-auto ${c.page}`}>
-      <h2 className="text-2xl font-bold mb-4">Image Uploader</h2>
-      <form onSubmit={onSubmit} className="space-y-3">
-        <Label htmlFor="photo">Photo</Label>
-        <Input id="photo" type="file" accept="image/*" onChange={onPickFile} className="w-full" />
-        <Input
-          type="text"
-          placeholder="Caption"
-          value={doc.caption}
-          onChange={(e) => merge({ caption: e.target.value })}
-          className="w-full"
-        />
-        <Button type="submit" size="lg">
-          Upload
-        </Button>
-        {saveError && <p role="alert" className="text-destructive">{saveError}</p>}
-      </form>
-
-      <h3 className="text-lg font-bold mt-8">Recent Uploads</h3>
-      <div className="grid grid-cols-2 gap-4 mt-2">
-        {docs.map((d) => (
-          <Card key={d._id}>
-            <CardContent>
-              {d._files?.photo?.url && <img src={d._files.photo.url} alt={d.caption || "upload"} className="w-full h-auto rounded-md" />}
-              <p className={`${c.meta} mt-2`}>{d.caption || "No caption"}</p>
-            </CardContent>
-          </Card>
-        ))}
-      </div>
+    <div className={c.page}>
+      <Stack gap={5}>
+        <Heading level={1}>Image Uploader</Heading>
+        <form onSubmit={onSubmit}>
+          <Stack gap={3}>
+            {/* A file picker hands over files, not a value, so it stays the browser's own control inside the Field. */}
+            <Field label="Photo">{(id, describedBy) => <input id={id} aria-describedby={describedBy} type="file" accept="image/*" onChange={onPickFile} />}</Field>
+            <Field label="Caption">
+              {(id, describedBy) => <Input id={id} describedBy={describedBy} value={doc.caption} onChange={(caption) => merge({ caption })} />}
+            </Field>
+            <Button type="submit" size="lg">
+              Upload
+            </Button>
+            {saveError && <ErrorNote>{saveError}</ErrorNote>}
+          </Stack>
+        </form>
+
+        <Heading level={2}>Recent Uploads</Heading>
+        <Grid cols={2} gap={4}>
+          {docs.map((d) => (
+            <Card key={d._id}>
+              <Stack gap={2}>
+                {d._files?.photo?.url && <Figure src={d._files.photo.url} alt={d.caption || "upload"} width={400} height={300} />}
+                <Text muted>{d.caption || "No caption"}</Text>
+              </Stack>
+            </Card>
+          ))}
+        </Grid>
+      </Stack>
     </div>
   );
 }
 ```
 
-For multi-file uploads (e.g. `<input multiple>`), build the `_files` map keyed by filename and iterate with `Object.entries(doc._files)` to render each entry.
+For multi-file uploads (the file picker with `multiple`), build the `_files` map keyed by filename and iterate with `Object.entries(doc._files)` to render each entry.
 
 Adding multi-file support:
 
@@ -756,7 +909,8 @@ Code listing for a bird sightings log App.jsx. Note the code ordering: hooks, th
 ```js
 import React from "react";
 import { useFireproof } from "use-fireproof";
-import { Button, Card, CardContent, Input, Label } from "@vibes.diy/look";
+import { Button, Field, Heading, Input, Row, RowCard, Spacer, Stack, Text } from "@vibes.diy/pouf";
+import { Checkbox } from "@vibes.diy/pouf/interactive";
 
 export default function App() {
   // 1. Hooks and document shapes
@@ -779,8 +933,8 @@ export default function App() {
   });
 
   // 2. Event handlers
-  const handleInputChange = (e) => {
-    mergeNewSighting({ species: e.target.value });
+  const handleInputChange = (species) => {
+    mergeNewSighting({ species });
   };
 
   const handleSubmit = (e) => {
@@ -788,48 +942,46 @@ export default function App() {
     submitNewSighting();
   };
 
-  // 3. ClassNames — right before JSX, for the plain elements only; the look's
+  // 3. ClassNames — right before JSX, for the plain elements only; the pouf
   // components carry their own surface, ink and shape.
   const c = {
-    page: "bg-background text-foreground font-sans",
-    meta: "text-muted-foreground",
+    page: "min-h-screen max-w-md mx-auto p-6 bg-background text-foreground font-sans",
   };
 
   // 4. JSX return
   return (
-    <div className={`min-h-screen max-w-md mx-auto p-6 ${c.page}`}>
-      <h2 className="text-2xl font-bold mb-4">Bird Sightings</h2>
-      <form onSubmit={handleSubmit} className="mb-4">
-        <Label htmlFor="species" className="mb-2 block">
-          Species
-        </Label>
-        <Input className="w-full" id="species" type="text" onChange={handleInputChange} value={newSighting.species} />
-      </form>
-      <ul className="space-y-3">
-        {sightings.map((doc) => (
-          <li key={doc._id}>
-            <Card>
-              <CardContent className="flex flex-col items-start">
-                <div className="flex items-center justify-between w-full">
-                  <div className="flex items-center">
-                    <input
-                      className="mr-2"
-                      type="checkbox"
-                      checked={doc.confirmed}
-                      onChange={() => database.put({ ...doc, confirmed: !doc.confirmed })}
-                    />
-                    <span className="font-medium">{doc.species}</span>
-                  </div>
-                  <Button variant="destructive" size="sm" onClick={() => database.del(doc._id)}>
-                    Delete
-                  </Button>
-                </div>
-                <div className={`${c.meta} mt-1`}>{new Date(doc.createdAt).toISOString()}</div>
-              </CardContent>
-            </Card>
-          </li>
-        ))}
-      </ul>
+    <div className={c.page}>
+      <Stack gap={5}>
+        <Heading level={1}>Bird Sightings</Heading>
+        <form onSubmit={handleSubmit}>
+          <Row gap={2} align="top">
+            <Field label="Species">
+              {(id, describedBy) => <Input id={id} describedBy={describedBy} onChange={handleInputChange} value={newSighting.species} />}
+            </Field>
+            <Button type="submit">Add</Button>
+          </Row>
+        </form>
+        <Stack gap={3}>
+          {sightings.map((doc) => (
+            <RowCard key={doc._id}>
+              <Row gap={3} align="center">
+                <Checkbox
+                  label={doc.species}
+                  checked={doc.confirmed}
+                  onChange={(confirmed) => database.put({ ...doc, confirmed: confirmed === true })}
+                />
+                <Spacer />
+                <Button type="button" variant="quiet" tone="down" size="sm" onClick={() => database.del(doc._id)}>
+                  Delete
+                </Button>
+              </Row>
+              <Text size="sm" muted>
+                {new Date(doc.createdAt).toISOString()}
+              </Text>
+            </RowCard>
+          ))}
+        </Stack>
+      </Stack>
     </div>
   );
 }

package/llms/image-gen.md

@@ -145,23 +145,26 @@ When each item's substance is its words — a generated joke, a short verse, a p
 
 ```jsx
 import { ImgGen, useImgGen } from "use-vibes";
+import { Button, RowCard, Text } from "@vibes.diy/pouf";
 
 function PunCard({ pun, database }) {
   const [wanted, setWanted] = React.useState(false);
   const { document: saved } = useImgGen({ _id: pun._id, database });
   const hasPicture = Object.keys(saved?._files ?? {}).length > 0;
   return (
-    <li>
-      <p>{pun.text}</p>
+    <RowCard>
+      <Text>{pun.text}</Text>
       {wanted || hasPicture ? (
         <figure>
           <ImgGen _id={pun._id} database={database} prompt={`A cheerful cartoon of this pun: ${pun.text}`} />
           {hasPicture ? null : <figcaption>Making a picture…</figcaption>}
         </figure>
       ) : (
-        <button onClick={() => setWanted(true)}>Picture this</button>
+        <Button type="button" size="sm" variant="quiet" onClick={() => setWanted(true)}>
+          Picture this
+        </Button>
       )}
-    </li>
+    </RowCard>
   );
 }
 ```
@@ -209,37 +212,51 @@ public facts. Public viewers render its `_files` URL with `<img>`; keep generati
 and revision controls on the creator's draft. Share the same `useImgGen` hook
 result between preview, download and publication so they select the same version.
 
-## Access Functions and `doc.type`
+## Access Functions and pictures
 
-If your app defines an access function that keys on `doc.type` (the common pattern — e.g. it throws `{ forbidden: "unknown document type" }` for any unenumerated type), be aware of how ImgGen sets `type`:
+Your `access.js` governs your app's own records — the story, the hat, the roast — and ImgGen keeps its pictures beside them in `media:<database>`, under the platform's media rules: every generation, a regenerate or an img2img edit included, is a new `version` record authored by whoever asked for it, and each person keeps their own `pointer` record for the picture they are viewing. So a type-keyed access function with one branch per record type already serves an image app, author checks and all; give each record the author and channel its own sharing calls for. When pictures should be more open or more closed than their record, write the access skill's media export, which checks that `doc.authorHandle` is the caller and admits both `version` and `pointer` records.
 
-- **Image attached to a host doc** (`<ImgGen _id={hostDoc._id} database={db} />`): the image inherits the host doc's existing `type` (`story`, `hat`, whatever) and its access/channels. The write passes a type-keyed access function with no extra work.
-- **Standalone image** (no `_id`, or a brand-new doc): the doc is written with `type: "image"`. A type-keyed access function will **reject** this unless it explicitly permits `"image"`. Add an `"image"` branch (with the grant/channel you want image docs to live on) so the write is accepted — otherwise image generation fails silently with `Failed to put document:`.
+## Choosing a Model
 
-Prefer attaching images to the host doc whose access you already grant; reach for standalone image docs only when you've added an `"image"` branch to the access function.
+Every `<ImgGen>` draws with the app's default image model. `listModels({ kind: "image" })` (from `call-ai`, beside `callAI`) returns the image models this app can use, the app's own choice first, and each entry's `id` goes straight into the `model` prop: `<ImgGen prompt="An astronaut riding a horse" model={m.id} />`. The entry with `isDefault: true` is the one ImgGen uses when `model` is left out; with `images` present the default is the platform's image-edit model instead, so img2img leaves `model` out (see above). When the app's maker saved their own provider key, it covers the image model they chose in settings; other models run on the person's credits. The callAI skill's "Choosing a model" section lists every field.
 
-**ImgGen does not stamp your app's author field.** The doc ImgGen writes (a standalone `type: "image"` doc, or the version it appends to a host doc) carries no `authorHandle`/`userHandle`/`senderHandle` of yours — that field is `null`/`undefined`. So an access-fn branch that author-gates the type ImgGen writes (`if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" }`) **rejects the write**: `null !== user.userHandle`, the signed-in maker included, and the image silently fails to persist as the doc you meant (`Failed to put document:`). Two fixes: (1) **attach the image to a host doc you created with the author field already stamped** — `<ImgGen _id={hostDoc._id} database={db} />` inherits the host's `type` and access, so the author check already passed when you wrote the host; this is the preferred shape. (2) For a genuinely **standalone** image doc, do NOT author-gate the `"image"` branch on strict author equality — route it to the channel you want and skip the author check (the platform's ImgGen write is server-authoritative, so there's no spoof to guard against). Never author-gate a type whose docs ImgGen originates without stamping the author yourself first.
+To compare image models, call `listModels({ kind: "image" })` and render one `<ImgGen>` per entry with `model={m.id}`. Every picture shares one prompt, each card is labelled with `m.name`, and each `_id` pairs the prompt with the model so a reload shows the saved pictures:
 
-**A version append (regenerate, or an img2img edit on an existing `_id`) arrives as the VIEWING user, not the original author.** So even when you DID stamp the author on the host doc, an `if (oldDoc && doc.authorHandle !== user.userHandle) throw { forbidden: "not author" }` on that type denies any _other_ signed-in viewer's generation on a shared/public-read doc — after the platform already billed it, arming an unbounded billed-retry loop (#3784/#3832). Author-equality belongs on **create and ownership change**, not on every update. Fix the author at create, forbid re-authoring, and for a non-author update accept only a legitimate ImgGen version append — the platform predicate `ctx.isImgGenVersionAppend(doc, oldDoc)` decides that (`oldDoc` is `null` on create):
+### `App.jsx`
+```jsx
+import React, { useEffect, useState } from "react";
+import { ImgGen } from "use-vibes";
+import { listModels } from "call-ai";
+import { Button, Card, Field, Grid, Input, Stack, Text } from "@vibes.diy/pouf";
 
-```js
-if (oldDoc === null) {
-  if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
-} else if (doc.authorHandle !== oldDoc.authorHandle) {
-  throw { forbidden: "cannot change author" };
-} else if (ctx.isImgGenVersionAppend(doc, oldDoc) === false && oldDoc.authorHandle !== user.userHandle) {
-  throw { forbidden: "not author" };
+export default function App() {
+  const [models, setModels] = useState([]);
+  const [message, setMessage] = useState("");
+  const [draft, setDraft] = useState("a penguin riding a bicycle");
+  const [prompt, setPrompt] = useState("a penguin riding a bicycle");
+  useEffect(() => {
+    listModels({ kind: "image" })
+      .then(setModels)
+      .catch((error) => setMessage(error.message));
+  }, []);
+  return (
+    <Stack>
+      <Field label="Picture">{(id) => <Input id={id} value={draft} onChange={setDraft} />}</Field>
+      <Button onClick={() => setPrompt(draft)} disabled={draft.trim().length === 0}>Draw it with every model</Button>
+      <Text>{message}</Text>
+      <Grid cols={3}>
+        {models.map((m) => (
+          <Card key={m.id}>
+            <ImgGen _id={`audition:${prompt}:${m.id}`} prompt={prompt} model={m.id} alt={`${prompt}, drawn by ${m.name}`} />
+            <Text>{m.isDefault ? `${m.name} · this app's default` : m.name}</Text>
+          </Card>
+        ))}
+      </Grid>
+    </Stack>
+  );
 }
 ```
 
-The platform predicate `ctx.isImgGenVersionAppend` accepts exactly one legitimate ImgGen version append by a non-author — prior versions/files and all other fields must be unchanged, so a field you didn't anticipate stays author-protected by default; deletes stay author-only. Because `versions`/`currentVersion` are among the version fields it allows, a non-author can also advance the DISPLAYED version (the shared-generation feature); guard `currentVersion` specifically if you need author-only display control.
-
-## Choosing a Model
-
-Override the model per component: `<ImgGen prompt="An astronaut riding a horse" model="openai/gpt-5-image-mini" />`
-
-Model ids follow the `provider/model-name` form from the platform's model catalog. Unknown ids surface as an error in the component's error UI.
-
 #### Props
 
 - `prompt`: text prompt (required unless `_id` is provided)
@@ -248,4 +265,4 @@ Model ids follow the `provider/model-name` form from the platform's model catalo
 - `database`: Fireproof db name or instance (default `"ImgGen"`)
 - `className`, `alt`, `style`: standard image styling
 - `showControls`: toggle regenerate + version nav (default `true`)
-- `model`: override the image-gen model for this component
+- `model`: an `id` from `listModels({ kind: "image" })` to draw with instead of the app's default