@vibes.diy/prompts 14.3.120 → 14.3.121

package/llms/fireproof.md

@@ -259,110 +259,91 @@ Address an existing record by its `_id`. `useDocument(task)` above holds the sel
 
 ## 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. Its sample records also populate the temporary, view-only preview
-while saving is being prepared; they become real saved records only through an
-explicit import. In that file, give each item a stable `key`; its derived identity
-is `seed:<key>`. References to another item use that derived identity. An `_id`
-that repeats the item's own derived identity is equivalent to leaving it out.
-Explicit singleton identities such as `config:board` remain available.
-
-Four rules make it hold:
+A person's own action — a tap, a submit, a pick — is what starts a write; nothing in the app writes on load or on mount. Starting state comes in three kinds, and none of them is written by the app's own code:
+
+- **A person's own starting state needs no record.** Their records live on the channel named by their handle (see `access.md`), so the app opens on their tree with nothing to create first, and the view renders its defaults — a name, a setting, an empty list's invitation — from constants until the person's own action saves one.
+- **App-wide named containers or participants the request requires** — the pottery studio and its named apprentice, the three projects in a studio, the rooms in a planner — are written by the agent building the app, with `put_doc` as the owner, once the build whose rules admit them is saved, then read back. That save is the owner's own action. The app's opening view shows them when they are there and an inviting add flow until they are.
+- **Example content stays the optional `seed.json` import** — believable entries the screenshot renders and the owner adds with one ask. A name present only in `seed.json` describes an offered import, not an existing record or grant. In that file, give each item a stable `key`; its derived identity is `seed:<key>`. References to another item use that derived identity. An `_id` that repeats the item's own derived identity is equivalent to leaving it out. Explicit singleton identities such as `config:board` remain available. The file also populates the temporary, view-only preview while saving is being prepared.
+
+Four rules make the required records 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 that
-  the enforced access rules do not admit yet is skipped quietly and retried on a
-  later run.
-- **Restrict their creation to the owner in `access.js`** when the records
-  describe the app itself rather than a visitor's own work.
-- **Write parents and membership grants before the records that depend on
-  them**, so a dependent document never lands against a container or a grant
-  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.
+  a second save of it lands on the same document instead of minting another.
+- **Gate their creation on a role in `access.js`** — `ctx.requireRole("owner")`,
+  or a role the owner hands out with a role record — when the records describe the
+  app itself rather than a visitor's own work.
+- **List parents and membership or role grants before the records that depend on
+  them**, so a dependent document never lands against a container or a grant that
+  does not exist yet.
+- **Leave the app's render paths write-free.** A write in an effect that fires when
+  a query reads empty runs on every fresh load, on every device and for every
+  visitor, because the live query renders empty before data arrives.
+
+Fixed ids are also what makes a repeated save safe: two devices saving the same
+record write the same document, and last-writer-wins converges on one copy.
 
 ### Match sample records to the owner's opening query
 
-The initial build's `<app-owner>` context supplies the app owner's handle.
-Use it to evaluate the opening query's group ID when writing `seed.json`.
-For an owner named `mira`, the runtime expression below selects `default-mira`,
-so every sample card in this opening board carries that exact `boardId`:
+The initial build's `<app-owner>` context supplies the app owner's handle. A
+sample record in the owner's own tree names that tree with `"@owner"` as the whole
+field value, which the platform fills in for whoever applies the seed. The opening
+view reads the signed-in person's own tree by their handle, so every sample card
+carries `"ownerHandle": "@owner"`:
 
 ```jsx
-const boardId = pickedBoardId ?? `default-${me?.userHandle}`;
-const { docs: cards } = useLiveQuery("boardId", { key: boardId });
+const { docs: cards } = useLiveQuery("ownerHandle", { key: me?.userHandle });
 ```
 
 ```json
 {
   "boards": [
-    { "key": "tent", "type": "card", "boardId": "default-mira", "text": "Blue tent, sleeps four" },
-    { "key": "stove", "type": "card", "boardId": "default-mira", "text": "Two-burner camp stove" },
-    { "key": "lantern", "type": "card", "boardId": "default-mira", "text": "Two rechargeable lanterns" },
-    { "key": "cooler", "type": "card", "boardId": "default-mira", "text": "Wheeled cooler" }
+    { "key": "tent", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Blue tent, sleeps four" },
+    { "key": "stove", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Two-burner camp stove" },
+    { "key": "lantern", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Two rechargeable lanterns" },
+    { "key": "cooler", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Wheeled cooler" }
   ]
 }
 ```
 
-Use the supplied owner handle in these parent IDs; keep the app's query
-and real writes driven by the current viewer and selected object. The database
-name, record type, parent references and query filters agree across the sample
-file and opening view. Later access rules preserve those parent references.
-The platform labels the temporary preview as sample data; those records reach
-persistent storage only through the person's explicit import.
+An id that only contains the handle (`settings-mira`) is not a whole value, so
+write the supplied owner handle into it literally; keep the app's query and real
+writes driven by the current viewer and selected object. The database name,
+record type, parent references and query filters agree across the sample file and
+opening view. Later access rules preserve those parent references. The platform
+labels the temporary preview as sample data; those records reach persistent
+storage only through the person's explicit import.
 
 ### 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.
+When an app ships with default content — starter slides, template rows, example cards — the content is a set of `seed.json` items, each with a **deterministic identity** (a stable `key`, or `_id: "seed:intro"`). This makes adding it **idempotent**: a second add 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.
+The app itself writes no copy. `useLiveQuery` renders empty before data arrives, so `docs.length === 0` is briefly true on **every** fresh load, and a "seed when empty" effect re-runs on every reload, every device and for every visitor. The empty view instead invites the person's own first action, and that action writes the record it checked:
 
 ### `App.jsx`
-```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() {
+```jsx partial
+function Deck() {
   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 the access rules before writing. A doc type the currently-enforced
-    // access rules don't allow 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} />;
+  // The person's own tap writes the first slide: the control checks this exact record.
+  const first = { type: "slide", title: "Welcome", position: 1000 };
+  const allowed = ready && can.create(first).ok;
+
+  if (slides.length === 0) {
+    return (
+      <Stack gap={2}>
+        <Text>Your deck is ready for its first slide.</Text>
+        <Button type="button" disabled={!allowed} onClick={() => allowed && database.put(first)}>
+          Add the first slide
+        </Button>
+      </Stack>
+    );
+  }
+  return <Slides 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 — channels, profiles, **seeds** — get deterministic `_id`s; event/content docs let `_id` auto-generate.
+Don't stamp `Date.now()` or other changing values into seed documents — that makes each re-add rewrite the doc with new content, churning revisions even though the `_id` is stable. Resource-like docs — channels, profiles, **seeds** — get deterministic `_id`s; event/content docs let `_id` auto-generate.
 
 ### Updating Documents in Event Handlers
 
@@ -454,7 +435,7 @@ A drag that touches many documents (painting pixels, drawing on a shared board)
 
 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.
+A draft reaches only the peers already subscribed to its channel, and a channel's grant comes from a saved document. The painter's own pointer-down saves a fixed-id room record on that channel before the first stroke is drawn, so the stroke is seen live; nothing writes on load or on mount.
 
 ### `App.jsx`
 ```jsx
@@ -485,12 +466,6 @@ function Canvas({ me }) {
   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";
@@ -504,6 +479,13 @@ function Canvas({ me }) {
     for (const [x, y] of stroke.cells) fill(x, y, stroke.color);
   }, [pixels, strokes, stroke, me]);
 
+  function startStroke(e) {
+    // The painter's own pointer-down saves the room record that grants the channel; the
+    // fixed id makes every later save the same document.
+    const room = { _id: "canvas:main", type: "canvas" };
+    if (ready && can.create(room).ok) database.put(room);
+    extendStroke(e);
+  }
   function extendStroke(e) {
     if (!canPaint) return;
     const r = canvasRef.current.getBoundingClientRect();
@@ -532,7 +514,7 @@ function Canvas({ me }) {
         className="w-full max-w-lg aspect-square touch-none"
         onPointerDown={(e) => {
           e.currentTarget.setPointerCapture(e.pointerId);
-          extendStroke(e);
+          startStroke(e);
         }}
         onPointerMove={(e) => e.buttons && extendStroke(e)}
         onPointerUp={endStroke}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.120",
+  "version": "14.3.121",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -39,10 +39,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/api-types": "14.3.120",
-    "@vibes.diy/call-ai-v2": "14.3.120",
-    "@vibes.diy/identity": "14.3.120",
-    "@vibes.diy/use-vibes-types": "14.3.120",
+    "@vibes.diy/api-types": "14.3.121",
+    "@vibes.diy/call-ai-v2": "14.3.121",
+    "@vibes.diy/identity": "14.3.121",
+    "@vibes.diy/use-vibes-types": "14.3.121",
     "arktype": "~2.2.6",
     "json-schema-faker": "~0.6.3"
   },