@vibes.diy/prompts 14.1.21 → 14.1.22

package/llms/fireproof.initial.md

@@ -0,0 +1,697 @@
+# Fireproof Database API Guide
+
+Fireproof is a document database with live sync, designed to make browser apps easy. On vibes.diy it runs against Firefly: each app holds a local replica (IndexedDB) that IS the database, so writes succeed locally and instantly and then sync in the background. The Firefly server validates every synced write on ingest and can still reject it (a conflict, or a write the platform does not admit); accepted writes stream live to every viewer. Use it in any JavaScript environment with a unified API that works both in React (with hooks) and as a standalone core API.
+
+## 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 (a refusal, a conflict): the local optimistic revision converges **server-wins**, and the platform surfaces a reason only when it has 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.
+- **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")`.
+
+**File structure:** A vibe's source is one or more files. `/App.jsx` is the entry point (React component).
+
+Fireproof enforces cryptographic causal consistency and ledger integrity using hash history, providing git-like versioning with lightweight blockchain-style verification. On vibes.diy, a write commits to the local replica immediately and syncs to the Firefly server in the background; the server is the authority on acceptance: it stores each document in a per-document append-only sequence, validates and routes it on ingest, and then syncs it to viewers. Because every synced write is validated server-side on ingest, it can be rejected.
+
+## Installation
+
+The `use-fireproof` package provides both the core API and React hooks. React hooks are the recommended way to use Fireproof in LLM code generation contexts. Fireproof databases persist data through the Firefly server and sync it live to every viewer. Each database is identified by a string name, and you can have multiple databases per application—often one per collaboration session, as they are the unit of sharing. Database names are the app's own to choose — pick a plain camelCase name for every database the app creates; prefix-namespaced names like `media:*` are platform-reserved for the databases platform components bring with them.
+
+Each document has an `_id`, which can be auto-generated or set explicitly. Auto-generation is recommended to ensure uniqueness and avoid conflicts. The server keeps a per-document sequence, so two clients writing the same `_id` at the same time can collide and one write will be rejected — see the note on continuous updates below. Prefer one document per event over many rapid writes to a single hot document.
+
+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 writes in `try/catch` to show denial errors to the user; 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.
+
+### Basic Example
+
+This complete app shows Fireproof's core: `useFireproof` gives you hooks, `useDocument` manages form state, and `useLiveQuery` sorts by `_id` for temporal ordering.
+
+App.jsx
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+
+export default function App() {
+  const { useDocument, useLiveQuery } = useFireproof("myLedger");
+
+  const { doc, merge, submit } = useDocument({ text: "" });
+
+  // _id is roughly temporal, this is most recent first
+  const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });
+
+  return (
+    <div>
+      <form onSubmit={submit}>
+        <input value={doc.text} onChange={(e) => merge({ text: e.target.value })} placeholder="New document" />
+        <button type="submit">Submit</button>
+      </form>
+
+      <h3>Recent Documents</h3>
+      <ul>
+        {docs.map((doc) => (
+          <li key={doc._id}>{doc.text}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+### Editing Documents
+
+Address documents by a known `_id` if you want to force conflict resolution or work with a real world resource, like a schedule slot or a user profile. In a complex app this might come from a route parameter or correspond to an outside identifier. To add a profile editor to the app above:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { doc, merge, submit } = useDocument({ text: "" });
+=======
+  const { doc, merge, submit } = useDocument({ text: "" });
+
+  const { doc: profile, merge: mergeProfile, save: saveProfile } = useDocument({ _id: "user-profile:abc@example.com" });
+>>>>>>> REPLACE
+```
+
+The `useDocument` hook provides several methods: `merge(updates)` updates the document with new fields without saving (use this instead of keeping a `useState` for document data), `submit(e)` handles form submission by preventing default, saving, and resetting, `save()` saves the current document state, and `reset()` resets to initial state. When you call submit, the document is reset, so if you didn't provide an `_id` then you can use the form to create a stream of new documents as in the basic example above.
+
+## Required starting records
+
+When a request names records the app must already have — the three projects in a
+studio, a template's starter rows, the rooms in a planner — those records are
+created by the app's own first render through the ordinary write path. That is
+the mechanism, and it is the same one described below for starter content.
+`seed.json` is a separate thing: an optional import a person runs by hand from
+the Data tab, applied by no deploy path, so a record that exists only there does
+not exist for anyone who opens the app.
+
+Four rules make it hold:
+
+- **Each required record gets a fixed `_id` you choose** (`"project:atlas"`), so
+  a second write of it lands on the same document instead of minting another.
+- **Create them after `ready` and after `can.create` says yes**, so a write the
+  platform does not admit yet is skipped quietly and retried on a later run.
+- **Write the object before the records that belong to it**, so a dependent
+  document never lands against a container that does not exist yet.
+
+Fixed ids are also what makes two tabs safe. Two browsers opening the app for the
+first time at the same moment both see an empty query and both write; with fixed
+ids those are two writes of the same document, and last-writer-wins converges on
+one copy. Reading the query first and then deciding whether to write is the shape
+that races — the read is empty in both tabs before either write lands.
+
+### How records are shaped
+
+Every record a person writes carries two things beyond its own content: **the id of the object it belongs to**, and **`authorHandle`, the handle of whoever wrote it**. The object itself carries **`creatorHandle`**. Write them at create and leave them alone afterwards — a later editor's handle then always finds the ids already on the doc rather than supplying one.
+
+Each signed-in person also gets **an object of their own with no doc to create**: its id is derived from their handle, `` `default-${me.userHandle}` ``. So someone who has just arrived types once and their first record lands, with nothing for them to set up first — and an app one person keeps for themselves is just this, with one object in it.
+
+```jsx
+import { useFireproof } from "use-fireproof";
+import { useVibe } from "use-vibes";
+
+function Board({ pickedBoardId }) {
+  const { useLiveQuery, database } = useFireproof("boards");
+  const { me, can } = useVibe("boards");
+  // No board doc needed to start: every person has one derived from their handle.
+  const boardId = pickedBoardId ?? `default-${me?.userHandle}`;
+  const { docs: cards } = useLiveQuery("boardId", { key: boardId });
+
+  // A card names its board and its author, both at create.
+  const addCard = (text) => database.put({ type: "card", boardId, authorHandle: me?.userHandle, text });
+  // A board someone explicitly makes names the person who made it.
+  const addBoard = (title) => database.put({ type: "board", creatorHandle: me.userHandle, title });
+
+  return (
+    <div>
+      {cards.map((card) => (
+        <p key={card._id}>{card.text}</p>
+      ))}
+      {can.create({ type: "card", boardId, authorHandle: me?.userHandle }).ok && <AddCardForm onAdd={addCard} />}
+    </div>
+  );
+}
+```
+
+Queries read off those same ids — `useLiveQuery("boardId", { key: boardId })` above — so the fields earn their place immediately rather than being bookkeeping for later.
+
+### Seeding starter data — give each seed a deterministic `_id`
+
+When an app ships with default content — starter slides, template rows, example cards — and writes it into the database on first load, give **each seed document a deterministic `_id`** (`"seed:intro"`, `"seed:" + key`). This makes the seeding write **idempotent**: if it ever runs again, it overwrites the same documents instead of creating fresh copies.
+
+The trap is the live-query empty state. `useLiveQuery` renders empty before data arrives, so `docs.length === 0` is briefly true on **every** fresh load — and a `useRef`/`useState` "already seeded" flag only guards the current session, never the next reload, a second device, or another collaborator. With **auto-generated** `_id`s, each of those re-seeds the full set and duplicate copies pile up without bound. Deterministic `_id`s collapse every re-seed back onto the same N documents.
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+import { useVibe } from "use-vibes";
+
+// Stable _id per seed, and no Date.now()/random fields — keep the payload
+// constant so a redundant seed is a true no-op, not a churning rewrite.
+const SEED = [
+  { _id: "seed:intro", type: "slide", title: "Welcome", position: 1000 },
+  { _id: "seed:problem", type: "slide", title: "The problem", position: 2000 },
+  { _id: "seed:ask", type: "slide", title: "The ask", position: 3000 },
+];
+
+export default function App() {
+  const { useLiveQuery, database } = useFireproof("deck");
+  const { ready, can } = useVibe("deck");
+  const { docs: slides } = useLiveQuery("position");
+
+  React.useEffect(() => {
+    if (slides.length > 0) return; // already has content — don't seed
+    // Ask `can.create` before writing. A doc type the platform doesn't admit
+    // yet (e.g. one this very edit just introduced — the update binds only
+    // after the whole turn lands) would be rejected: skip quietly now and seed
+    // on a later run instead of spamming errors.
+    if (!ready || !can.create(SEED[0]).ok) return;
+    // Deterministic _id → idempotent. Even if this runs again (another load or
+    // device before the query resolves), it overwrites the same docs instead of
+    // minting new ones, so seed slides never duplicate.
+    SEED.forEach((s) => database.put(s).catch((e) => console.error(e)));
+  }, [slides.length, ready, can, database]);
+
+  return <Deck slides={slides} />;
+}
+```
+
+Don't stamp `Date.now()` or other changing values into seed documents — that makes each re-seed rewrite the doc with new content, churning revisions even though the `_id` is stable. Resource-like docs — categories, profiles, **seeds** — get deterministic `_id`s; event/content docs let `_id` auto-generate.
+
+### Updating Documents in Event Handlers
+
+To update an existing document from a click handler or callback, use `database.put()` directly. Never call `useDocument` inside an event handler — that violates React's Rules of Hooks. Adding a toggle to list items:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { useDocument, useLiveQuery } = useFireproof("myLedger");
+=======
+  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
+>>>>>>> REPLACE
+```
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+          <li key={doc._id}>{doc.text}</li>
+=======
+          <li key={doc._id}>
+            {doc.text}
+            <button onClick={() => database.put({ ...doc, favorite: !doc.favorite })}>
+              {doc.favorite ? "★" : "☆"}
+            </button>
+          </li>
+>>>>>>> REPLACE
+```
+
+Never call hooks inside handlers — `const { doc, save } = useDocument({ _id: id })` inside an onClick BREAKS the Rules of Hooks.
+
+### 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:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
+=======
+  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
+
+  // 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 });
+>>>>>>> REPLACE
+```
+
+App.jsx
+
+```jsx
+<<<<<<< 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
+        onPointerUp={() => saveMix().catch((err) => console.error("save failed", err))} // one write on commit
+      />
+
+      <h3>Recent Documents</h3>
+>>>>>>> REPLACE
+```
+
+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.
+
+### 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.
+
+#### Query by Key Range
+
+Passing a string to `useLiveQuery` will index by that field. Use the key argument to filter by a specific value, or range for bounded queries. Switching from temporal to filtered query:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });
+=======
+  // all docs where doc.agentName === "agent-1", sorted by _id
+  const { docs } = useLiveQuery("agentName", { key: "agent-1" });
+>>>>>>> REPLACE
+```
+
+Or query a numeric range:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { docs } = useLiveQuery("agentName", { key: "agent-1" });
+=======
+  // docs with agentRating between 3 and 5
+  const { docs } = useLiveQuery("agentRating", { range: [3, 5] });
+>>>>>>> REPLACE
+```
+
+#### Counter Pattern
+
+Documents can be updated by multiple clients, and synced later. To create an event counter, don't increment a number on a single doc, instead write a small document per counted event, and query them with an index:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { docs } = useLiveQuery("agentRating", { range: [3, 5] });
+=======
+  // The counter's scope: the board being viewed and who is counting (useVibe from "use-vibes", as above).
+  const { me } = useVibe("boards");
+  const boardId = `default-${me?.userHandle}`;
+  // Keyed on the board AND the event name, so one board's count never includes another board's events.
+  const { docs } = useLiveQuery((doc) => [doc.boardId, doc.counter], { key: [boardId, "my-event-name"] });
+  const counterValue = docs.length;
+
+  // Each counted event is its own record, and it names the board it belongs to and who wrote it.
+  function countEvent() {
+    database.put({ type: "count", counter: "my-event-name", boardId, authorHandle: me?.userHandle });
+  }
+>>>>>>> REPLACE
+```
+
+This pattern ensures the count is accurate even during sync — each event is its own document, so concurrent writes never conflict.
+
+### Custom Indexes
+
+Use a custom index function to normalize and transform document data, for instance if you have both new and old document versions in your app:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  // The counter's scope: the board being viewed and who is counting (useVibe from "use-vibes", as above).
+  const { me } = useVibe("boards");
+  const boardId = `default-${me?.userHandle}`;
+  // Keyed on the board AND the event name, so one board's count never includes another board's events.
+  const { docs } = useLiveQuery((doc) => [doc.boardId, doc.counter], { key: [boardId, "my-event-name"] });
+  const counterValue = docs.length;
+
+  // Each counted event is its own record, and it names the board it belongs to and who wrote it.
+  function countEvent() {
+    database.put({ type: "count", counter: "my-event-name", boardId, authorHandle: me?.userHandle });
+  }
+=======
+  const { docs } = useLiveQuery(
+    (doc) => {
+      if (doc.type == "listing_v1") return doc.sellerId;
+      else if (doc.type == "listing") return doc.userId;
+    },
+    { key: routeParams.sellerId }
+  );
+>>>>>>> REPLACE
+```
+
+#### Array Indexes and Prefix Queries
+
+When you want to group rows easily, you can use an array index key. This is great for grouping records by year/month/day or other paths. The prefix query is a shorthand for a key range:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { docs } = useLiveQuery(
+    (doc) => {
+      if (doc.type == "listing_v1") return doc.sellerId;
+      else if (doc.type == "listing") return doc.userId;
+    },
+    { key: routeParams.sellerId }
+  );
+=======
+  const { docs } = useLiveQuery(
+    (doc) => {
+      const date = new Date(doc.date);
+      if (Number.isNaN(date.getTime())) return; // return nothing to skip docs without a valid date
+      return [date.getFullYear(), date.getMonth(), date.getDate()];
+    },
+    { prefix: [2024, 11] } // everything from November 2024
+  );
+>>>>>>> REPLACE
+```
+
+#### Sortable Lists
+
+Sortable lists are a common pattern. Use evenly spaced positions and insert between items using midpoint calculation:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { docs } = useLiveQuery(
+    (doc) => {
+      const date = new Date(doc.date);
+      if (Number.isNaN(date.getTime())) return;
+      return [date.getFullYear(), date.getMonth(), date.getDate()];
+    },
+    { prefix: [2024, 11] }
+  );
+=======
+  // Query items on list xyz, sorted by position
+  // Note: useLiveQuery('listId', { key:'xyz' }) would be the same docs, sorted chronologically by _id
+  const { docs } = useLiveQuery((doc) => [doc.listId, doc.position], { prefix: ["xyz"] });
+
+  // Each item names the list it belongs to and who wrote it, both at create.
+  async function initializeList() {
+    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: 1000 });
+    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: 2000 });
+    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: 3000 });
+  }
+
+  async function insertBetween(beforeDoc, afterDoc) {
+    const newPosition = (beforeDoc.position + afterDoc.position) / 2;
+    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: newPosition });
+  }
+>>>>>>> REPLACE
+```
+
+## 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. A refusal or 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 it has 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.
+
+```js
+// Default (single-user apps): durable offline writes, no config needed.
+const { useLiveQuery } = useFireproof("todos");
+
+// Collaborative app: fail fast instead of queueing a stale write.
+const { useLiveQuery } = useFireproof("shared-board", { offlineQueue: false });
+```
+
+## Anonymous writes (local-first by default)
+
+Letting a logged-out visitor try the app and build a little state before signing in needs **no opt-in** — it is the universal default on every vibe. While logged out, `put`/`del`/`useLiveQuery`/`useDocument` run against the local replica with the identical API — no auth branching in your code — so favorites, a draft, or a scratch list just work. On first sign-in that local state drains automatically into the user's cloud database and then syncs live; nothing is lost if a drain is interrupted. The sign-in and drain-confirmation toast ("saved to your account") is platform-provided chrome — do not build your own "saved"/"synced" notice for it.
+
+The old `{ anonymousLocal: true }` option (and its `migrate` hook) is **deprecated and ignored** — its behavior is now the default, so the runtime warns once and drains any legacy data on its own. Do not emit the flag in new code.
+
+---
+
+## 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 on ingest, persisted, and then synced to every viewer who may read it. 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 it has 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
+
+You can use the core API outside a React component — in a plain script or a helper module. Instead of hooks, import the core API directly:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+import React from "react";
+import { useFireproof } from "use-fireproof";
+
+export default function App() {
+  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
+=======
+import { fireproof } from "use-fireproof";
+
+const database = fireproof("myLedger");
+
+// The document API is async — reads and writes both await the server.
+// Writes can fail (refused, conflict, network), so wrap them.
+async function main() {
+  try {
+    const ok = await database.put({ text: "Sample Data" });
+    const doc = await database.get(ok.id);
+    const latest = await database.query("_id", { limit: 10, descending: true });
+    console.log("Latest documents:", latest.docs);
+  } catch (err) {
+    console.error("write failed (refused, conflict, or network):", err);
+  }
+}
+>>>>>>> REPLACE
+```
+
+### Working with Files
+
+Fireproof documents carry attachments under `_files`. Save a `File` (or `Blob`) by assigning it to a key on `_files`, and Fireproof handles upload, durable storage, and URL minting for you. After a doc round-trips through the database, each `_files.<key>` entry carries a stable `url` you can drop straight into `<img>`, `<video>`, `<audio>`, CSS `background-image`, etc.
+
+Each `_files.<key>` entry shape after save + round-trip: `{ url: string, type: string, size: number, lastModified?: number, file: () => Promise<File> }`. The platform-minted `url` is stable for the lifetime of that file, so the browser cache works normally. For plain `<img>` rendering, prefer `meta.url` — it skips one fetch and lets the browser handle cache and decoding. Use `meta.file()` only when you need the bytes themselves (transcoding, hashing, ML features).
+
+Building an image uploader with `_files`:
+
+App.jsx
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+
+export default function App() {
+  const { useDocument, useLiveQuery } = useFireproof("imageUploads");
+
+  const { doc, merge, submit } = useDocument({
+    _files: {},
+    caption: "",
+    type: "upload",
+    createdAt: Date.now(),
+  });
+
+  const { docs } = useLiveQuery("type", { key: "upload", descending: true, limit: 12 });
+
+  const onPickFile = (e) => {
+    const f = e.target.files?.[0];
+    if (f) merge({ _files: { photo: f } });
+  };
+
+  const onSubmit = (e) => {
+    e.preventDefault();
+    if (!doc._files?.photo) return;
+    submit();
+  };
+
+  const c = {
+    bg: "bg-white",
+    card: "bg-gray-50",
+    border: "border-gray-200",
+    accent: "bg-blue-500 hover:bg-blue-600",
+    text: "text-gray-700",
+  };
+
+  return (
+    <div className={`p-6 max-w-lg mx-auto ${c.bg} shadow-lg rounded-lg`}>
+      <h2 className="text-2xl font-bold mb-4">Image Uploader</h2>
+      <form onSubmit={onSubmit} className="space-y-3">
+        <input type="file" accept="image/*" onChange={onPickFile} className={`w-full ${c.border} border rounded p-2`} />
+        <input
+          type="text"
+          placeholder="Caption"
+          value={doc.caption}
+          onChange={(e) => merge({ caption: e.target.value })}
+          className={`w-full ${c.border} border rounded p-2`}
+        />
+        <button type="submit" className={`px-4 py-2 ${c.accent} text-white rounded`}>
+          Upload
+        </button>
+      </form>
+
+      <h3 className="text-lg font-semibold mt-6">Recent Uploads</h3>
+      <div className="grid grid-cols-2 gap-4 mt-2">
+        {docs.map((d) => (
+          <div key={d._id} className={`${c.border} border p-2 rounded shadow-sm ${c.card}`}>
+            {d._files?.photo?.url && <img src={d._files.photo.url} alt={d.caption || "upload"} className="w-full h-auto rounded" />}
+            <p className={`text-sm ${c.text} mt-2`}>{d.caption || "No caption"}</p>
+          </div>
+        ))}
+      </div>
+    </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.
+
+Adding multi-file support:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const onPickFile = (e) => {
+    const f = e.target.files?.[0];
+    if (f) merge({ _files: { photo: f } });
+  };
+
+  const onSubmit = (e) => {
+    e.preventDefault();
+    if (!doc._files?.photo) return;
+    submit();
+  };
+=======
+  const onPickFile = (e) => {
+    const next = {};
+    for (const f of e.target.files) next[f.name] = f;
+    merge({ _files: next });
+  };
+
+  const onSubmit = (e) => {
+    e.preventDefault();
+    if (!Object.keys(doc._files || {}).length) return;
+    submit();
+  };
+>>>>>>> REPLACE
+```
+
+### Form Validation
+
+You can use React's `useState` to manage validation states and error messages. Validate inputs at the UI level before allowing submission. Adding validation to the uploader:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const onSubmit = (e) => {
+    e.preventDefault();
+    if (!Object.keys(doc._files || {}).length) return;
+    submit();
+  };
+=======
+  const [errors, setErrors] = React.useState({});
+
+  function validateForm() {
+    const newErrors = {};
+    if (!doc.caption.trim()) newErrors.caption = "Caption is required.";
+    if (!Object.keys(doc._files || {}).length) newErrors.file = "Pick a file.";
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }
+
+  const onSubmit = (e) => {
+    e.preventDefault();
+    if (validateForm()) submit();
+  };
+>>>>>>> REPLACE
+```
+
+## Example React Application
+
+Code listing for todo tracker App.jsx. Note the code ordering: hooks, then handlers, then classNames right before JSX.
+
+```js
+import React from "react";
+import { useFireproof } from "use-fireproof";
+import { useVibe } from "use-vibes";
+
+export default function App() {
+  // 1. Hooks and document shapes
+  const { useLiveQuery, useDocument, database } = useFireproof("todoList");
+  const { me } = useVibe("todoList");
+
+  // Every person has a list of their own without creating one first.
+  const listId = `default-${me?.userHandle}`;
+
+  const {
+    doc: newTodo,
+    merge: mergeNewTodo,
+    submit: submitNewTodo,
+  } = useDocument({
+    todo: "",
+    type: "todo",
+    listId, // the list this todo belongs to, on the todo itself
+    authorHandle: me?.userHandle,
+    completed: false,
+    createdAt: Date.now(),
+  });
+
+  const { docs: todos } = useLiveQuery("listId", {
+    key: listId,
+    descending: true,
+  });
+
+  // 2. Event handlers
+  const handleInputChange = (e) => {
+    mergeNewTodo({ todo: e.target.value });
+  };
+
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    submitNewTodo();
+  };
+
+  // 3. ClassNames — right before JSX so colors stay consistent
+  const c = {
+    bg: "bg-white",
+    card: "bg-gray-50",
+    border: "border-gray-200",
+    accent: "bg-[#e63946]",
+    text: "text-gray-500",
+  };
+
+  // 4. JSX return
+  return (
+    <div className={`max-w-md mx-auto p-4 ${c.bg} shadow rounded`}>
+      <h2 className="text-2xl font-bold mb-4">Todo List</h2>
+      <form onSubmit={handleSubmit} className="mb-4">
+        <label htmlFor="todo" className="block mb-2 font-semibold">
+          Todo
+        </label>
+        <input
+          className={`w-full ${c.border} border rounded px-2 py-1`}
+          id="todo"
+          type="text"
+          onChange={handleInputChange}
+          value={newTodo.todo}
+        />
+      </form>
+      <ul className="space-y-3">
+        {todos.map((doc) => (
+          <li className={`flex flex-col items-start p-2 ${c.border} border rounded ${c.card}`} key={doc._id}>
+            <div className="flex items-center justify-between w-full">
+              <div className="flex items-center">
+                <input
+                  className="mr-2"
+                  type="checkbox"
+                  checked={doc.completed}
+                  onChange={() => database.put({ ...doc, completed: !doc.completed })}
+                />
+                <span className="font-medium">{doc.todo}</span>
+              </div>
+              <button className={`text-sm ${c.accent} text-white px-2 py-1 rounded`} onClick={() => database.del(doc._id)}>
+                Delete
+              </button>
+            </div>
+            <div className={`text-xs ${c.text} mt-1`}>{new Date(doc.createdAt).toISOString()}</div>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+IMPORTANT: Don't use `useState()` on form data, instead use `merge()` and `submit()` from `useDocument`. Only use `useState` for ephemeral UI state (active tabs, open/closed panels, cursor positions). Keep your data model in Fireproof.